Slashdot Mirror
Documentation Strategies?
An anonymous reader asks: "I'm a developer and have been given a task of creating documentation, for fellow developers, on how the system (a CMS) I have implemented, and adapted, works and how to develop for it. On the surface it doesn't seem too complicated but the amount of information I need to get down on paper, and the level of detail needed on some parts, is great. What's the best way to approach this task when there's so much information bouncing about in your head you don't know where to start?"
Write a mindmap first. That way you can ensure you've got the whole thing laid out sensibly; transferring the mindmap into a document is usually fairly straightforward.
-WolfWithoutAClause
"Gravity is only a theory, not a fact!"Didn't we just have an article about training replacements? Sounds suspiciously like exactly that.
But it is also possible that this documentation could be used by FAEs who need to have this kind of detailed documentation so that their job becomes easier, more easily repeatable, and faster.
Good documentation is a great thing when it is used for good, it brings customer complaints down and possibly increases revenue. But the double edge also makes it possible to replace the experts with trained monkeys who only know how to follow the docs without an understanding of the product.
I have been pwned because my
I tend to
-make an outline, or TOC for the final docs as I visualize
-make a formatted template for the entire document(s) in the word processor
-do the project, or what ever your work is
Keep a textfile open the whole time with the outline, take notes every day under each outline topic I'm working on.
Final step is just turn the notes into real prose.
Drop it into the templated final docs.