HN Explorer

Ask HN: How can a developer become good at documentation

2 points by g123g ↗ HN
I have been coding all my life with most of the documentation limited to the comments I put in the code. But in my new role, I need to document the existing designs, architectures of the existing or proposed systems, prepare presentations for upper management etc. I am somehow getting this done but I don't see the end result as particularly appealing.

Are there any guidelines or a set of rules that I can follow. Also how can I get those nice graphics/flowcharts etc. into the documents, are there any good tools that anyone can recommend.

1 comment

[ 3.0 ms ] story [ 11.4 ms ] thread
makecheck
I personally like documentation to be brief. This is easier if you are targeting management, because they're not going to digest details anyway, so you only include the essentials.

Brevity helps maintainability. It increases the chance of correctness. It also saves time; you will never anticipate every question, so it is far better to document some basics and instead just expect to answer questions periodically.

To be able to answer questions, you should document the people involved with each part of a system. This makes it incredibly obvious if you have any holes (i.e. is there any place in the system where, if ONE guy leaves the company, you're screwed?).

OmniGraffle (on the Mac) is an outstanding tool for making various charts.