Cell Phone Software Forum
| View previous topic :: View next topic |
| Author |
Message |
John Carter
Guest
|
 Posted: Mon Apr 02, 2007 5:59 am Post subject: Live Documentation, Transparent Architecture.. |
 |
|
I'm thunking Deep Thoughts about Documentation and Architecture and have
these questions for you...
By "Document" I mean text documents, diagrams, architectural diagrams,
protocol specs, hardware diagrams, requirement specs, ...
1. How do your developers find the right document to read?
2. How do the _know_ it is the right version...
* For this development branch
* For this release. (Historical)
* For this hardware version.
* For this product variant.
3. Do you, and if you do, how do you keep the docs in synch with the code?
4. How do you keep the Document Live? ie. Uptodate, known about, read,
relevant, well loved and used.
5. Do you, and if you do, how do you keep the uptodate and current docs
from being such warm fuzzy cloud diagrams that they bear no reality to the
code.
6. If you were to plaster the walls with information radiators (A0
posters) about your system. What would the be?
--
John Carter Phone : (64)(3) 358 6639
Tait Electronics Fax : (64)(3) 359 4632
PO Box 1645 Christchurch Email : john.carter@tait.co.nz
New Zealand |
|
| Back to top |
|
 |
| |
Ads |
Advertising
Sponsor
|
|
H. S. Lahman
Guest
|
| Posted: Mon Apr 02, 2007 8:19 pm Post subject: Re: Live Documentation, Transparent Architecture.. |
|
|
Responding to Carter...
| Quote: |
By "Document" I mean text documents, diagrams, architectural diagrams,
protocol specs, hardware diagrams, requirement specs, ...
1. How do your developers find the right document to read?
|
Provide a repository in the form of a local web site. Then you can
provide all the indexing and whatnot you need. Google task: the process
frameworks like CMM and ISO have commercial tools available that provide
exactly this sort of thing OTS.
| Quote: |
2. How do the _know_ it is the right version...
* For this development branch
* For this release. (Historical)
* For this hardware version.
* For this product variant.
|
Put everything under version control. The links from (1) go to the right
version.
| Quote: |
3. Do you, and if you do, how do you keep the docs in synch with the code?
|
I'm a translationist, so the diagrams are /always/ in synch with the
code. B-))
However, the answer for other documentation or elaboration is: process.
Keeping things in synch is a process issue for the shop. It is
fundamentally no different than using the right build file/options,
using the right test suite, or shipping the right DLLs. The developers
just have to follow the process (e.g., (1) update the specs; (2) update
the models; (3) update the code).
Hint: put the documentation under version control using the same
nomenclature as the the software builds/releases.
| Quote: |
4. How do you keep the Document Live? ie. Uptodate, known about, read,
relevant, well loved and used.
|
If the documentation is useful, people will access it. Making it easy to
access if a job for (1). Making it known is a matter of educating new
hires about (1) and having a notification process when new stuff is
added to (1).
| Quote: |
5. Do you, and if you do, how do you keep the uptodate and current docs
from being such warm fuzzy cloud diagrams that they bear no reality to the
code.
|
Every work product is peer reviewed, including documentation.
| Quote: |
6. If you were to plaster the walls with information radiators (A0
posters) about your system. What would the be?
|
Plaster the walls with metrics, not documentation.
Spending time on the infrastructure for (1) to ensure ease of use (e.g.,
hidden links to version control) is well worthwhile. But one also needs
to spend time on process infrastructure so that everyone knows that when
X is changed Y and Z also need to be updated and there is traceability
to whether Y and Z actually were updated.
Bottom line: I think it is a pure process and infrastructure issue.
*************
There is nothing wrong with me that could
not be cured by a capful of Drano.
H. S. Lahman
hsl@pathfindermda.com
Pathfinder Solutions
http://www.pathfindermda.com
blog: http://pathfinderpeople.blogs.com/hslahman
"Model-Based Translation: The Next Step in Agile Development". Email
info@pathfindermda.com for your copy.
Pathfinder is hiring:
http://www.pathfindermda.com/about_us/careers_pos3.php.
(888)OOA-PATH |
|
| Back to top |
|
|
| |
Ads |
Advertising
Sponsor
|
|
JXStern
Guest
|
| Posted: Wed Apr 04, 2007 5:43 am Post subject: Re: Live Documentation, Transparent Architecture.. |
|
|
On Mon, 02 Apr 2007 13:59:30 +1200, John Carter
<john.carter@tait.co.nz> wrote:
| Quote: |
I'm thunking Deep Thoughts about Documentation and Architecture and have
these questions for you...
By "Document" I mean text documents, diagrams, architectural diagrams,
protocol specs, hardware diagrams, requirement specs, ...
1. How do your developers find the right document to read?
|
Ask, and ye shall receive.
| Quote: |
2. How do the _know_ it is the right version...
* For this development branch
* For this release. (Historical)
* For this hardware version.
* For this product variant.
|
Historical, huh? Yes, well. Look, if you're the kind of organization
that ships product in a dozen variants, then the docs should be under
source control right beside the code. Front page should have all
sorts of markers on it, but the main thing is that it's in the right
place, that somebody(s) TRY to get it right.
Many errors will occur, yet it is worth the effort.
| Quote: |
3. Do you, and if you do, how do you keep the docs in synch with the code?
|
With great difficulty, and unfortunately at about the lowest priority.
| Quote: |
4. How do you keep the Document Live? ie. Uptodate, known about, read,
relevant, well loved and used.
|
Wait for someone to screw up, then send it to them.
| Quote: |
5. Do you, and if you do, how do you keep the uptodate and current docs
from being such warm fuzzy cloud diagrams that they bear no reality to the
code.
|
Don't write them in the first place, or at least don't bother to
update them. Unless you have reverse-engineering tools or other MDA
that does it automagically.
| Quote: |
6. If you were to plaster the walls with information radiators (A0
posters) about your system. What would the be?
|
Walls? Since when do modern developers have walls?
Well, such walls as I'm near, do get plastered with my docs. I'm
doing almost entirely database anymore, so I post (partial) ER
diagrams first, job schedules, dependency diagrams, also process
related stuff like bulleted requirements lists and project Gantt
chart. And as space allows, inspiring words from Fearless Leader
about our goals and achievements.
--
Documentation is both a tool and a work product, it has costs and
benefits. If management recognizes the benefits, it will usually wish
to incur the costs. Where management doesn't care, very few modern
developers will make any efforts in doc.
And oh yeah, emphasize INTERNAL DOCUMENTATION, eg comments in the
code! Within reason, but >> 0. It still gets out of sync, etc, but I
give it priority over external docs.
J. |
|
| Back to top |
|
|
| |
Ads |
Advertising
Sponsor
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
223 Attacks blocked
Powered by phpBB © 2001, 2005 phpBB Group
|
FAQ
Search
Memberlist
Usergroups
Register
Profile
Log in to check your private messages
Log in
