Ask HN: How do you document the development process?
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.
5 comments
[ 3.9 ms ] story [ 11.2 ms ] threadI 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).
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.
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.