Ask HN: How do you document the development process?

8 pointsby timelinexvor 16 Jahren5 comments

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.

What I'm looking for is how this process is done in other companies. Also, I'm going about the documentation process correctly?

Any input would be greatly appreciated.

1 comments

jacquesmvor 16 Jahren

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).

timelinexvor 16 Jahren

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

jacquesmvor 16 Jahren

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.

timelinexvor 16 Jahren

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.

jacquesmvor 16 Jahren

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).