

Ask HN: How do you document the development process? - timelinex

Currently, I am working on a project and I am wondering what is the best way to go about documenting it.  I am documenting in the code but also I crate design documents.  The design documents contains for every class develop: why I wrote that class, how the class was implemented, advantages and disadvantages of the class, discussion about the class, example inputs and example of the class.  As you can see the design document would be rather time consuming to produce.  The main purpose of the design doc is to keep my supervisor informed, who is a remote location. and also to track the decision that are made over the course of the project.<p>What I'm looking for is how this process is done in other companies.  Also, I'm going about the documentation process correctly?<p>Any input would be greatly appreciated.
======
jacquesm
Put up a local wiki and store that stuff in there. We do this with 'trac', it
also has a great ticketing system built in.

I do technical due diligence for a living and whenever I have to do this at a
company that has a wiki with all the documentation in it I'm so happy because
it will save me a day or two, and on top of that I know that their developers
will have quick access to all that stuff as well.

Usually I make a point of noting in the final report that the documentation
was well organized if this is the case (and the wiki isn't a huge mess,
unfortunately that is still a possibility).

~~~
timelinex
So, what exactly do you document? Do you feel I'm over documenting?

~~~
jacquesm
Over-documenting is when you document stuff that you will not need to read at
any point in the future, that's a good question to ask yourself:

Will I need this again?

If the answer is absolutely not, don't bother, if the answer is 'yes' or 'I
don't know' safe is better than sorry..

The most important things to document are high level stuff how the system as a
whole operates so that a person that is new to the company can quickly place
their work in context, and then lower level stuff that helps them with the
actual work.

For instance, interfaces, boundaries between systems and subsystems are very
important to document, as is the function of various modules.

Internal libraries deserve a solid section of their own.

It is very hard to give you an exact guideline here, but your gut should tell
you for the most part whether something needs documentation or can stand by
itself.

A good rule is probably that documentation serves to increase understanding,
if it doesn't do that you can leave it out.

~~~
timelinex
Ok thanks for the help. At a gut level, I think i'm over documenting.

I dont think any documentation would be lost if somehow I leave some of it
out. Since, it would be in the code and I would just need to abstract it out,
if it's needed by someone.

~~~
jacquesm
You're welcome! Good luck with it, setting up trac can take you a couple of
hours (if you decide to go for that solution).

