

Ask HN: How can a developer become good at documentation - g123g

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.<p>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.
======
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.

