: Re: How does one avoid incomplete changes to documentation? Having encountered errors in technical documentation that almost certainly came from incomplete editing after copying from earlier documentation,

@Angela458

Vote Up Vote Down

The code is already a form of documentation of what the system does. That is rather much the point of high level language code, to ease the understanding of systems for human readers of it.

This is a hint to a solution. Ask yourself, "who is the documentation for?" Is it for programmers to communicate to other programmers within your organization? Then do what you can to make the code clear, concise, not surprising, and DRY. DRY is about the future more than it is about the present.

And there is no point to keeping broken documentation. You would be better off discarding the docs and eliminating any chance someone might make a technical error by trusting potentially erroneous documentation. Bad documentation isn't known to be bad until it blows up in your face. Until then, it provides a false sense of security.

Is it for a program manager? Then seek to write documentation that is clear, concise, and doesn't hide behind technical buzzwords and faux legalese. Most people don't keep up with documentation because they find it difficult to understand what is already written, difficult to emulate the style, and despise doing make-work. There is little point in putting minute technical detail into documentation. Otherwise, we would have designed a programming language that uses MS Word documents as source files.

Is it for users? Then your documentation is part of your product. You need to dedicate specific time, and probably specific people who make careers out of writing use documentation, to the tasks. The project iteration is no more complete without the user documentation--a form of user interface--than the features it would cover. I tend to prefer to put such explanatory text on the screen next to the feature.

And that is generally a problem with all parts of a system: how closely located are tightly coupled components? You will see it happen in you database schema definitions if you manage them through raw SQL scripts. It will happen to reports generated in your system if the report code is "far away" from the report UI. Keeping related bits of the system located together is the only way to avoid them drifting apart, like some two samples of a species diverging over time after getting separated by an ocean.

Also realize that you don't have to follow the "obvious" process for writing documentation that program managers always seem to love. The last time I worked in a heavily documented environment, I spent at least 50% of my time on documentation. But though my program manager wanted the documentation written before the code, I did no such thing. I wrote them in tandem. I needed to write the code to figure out what would go in the documentation. I was lauded for having the best documentation and deadline rate in the company.

But the moral of the story is not "do it my way". It is that every company has its own culture that will value certain things over others. Use that knowledge to your advantage. Steal coding time from documentation time or vice versa. Write whatever code you have to to automate repetitive tasks. Question fundamental assertions and seek to minimize the work load.

(0)

Login to post a comment!