I am trying to start a documentation about a class library that is already finished/developed.
The purpose of the documentation is to be used by other developers in order to understand what kind of methods are included in this class library and how to use them. More specifically documentation like Javadoc tool that provides based on XML comments for each method and attribute of classes.
So far I have been reading about documentation type and it seems that Technical Specification and Software Design Documentation are those that provide such information.
But I am confused about them because I can not see a lot of differences based on some reading that I have already done.
For example here, it says that Software Design Documentation is used to give a software development team overall guidance to the architecture of the software project. And here it says that Technical Documentation is used for a new developer that join a software project. What kind of information would be useful to get introduced to the project?
From this point of view, it seems that those documentation tries to make a software developer familiar with what has been developed so far. But what is the difference and which one to use for my purpose?
Best Answer
What is a technical documentation ?
The real definition: Technical documentation means any document that common mortals do not understand because of some required specialized knowledge.
The bad news is that it won't help you to determine what to put in it. The good news is that you can from now on use the concept yourself to qualify anything that you do not understand: "Uh! These accounting guidelines seem to be a very technical document" (and all those except the accountants will nod, silently agreeing with you).
What is the objective of your documentation?
The real question: For technical writing, as for any writing, the first question is to know what is the target audience, and what the primary purpose of this documentation is:
A fatal assumption would be to think that you could do a "technical documentation" that would cover any technical needs. The level of details to be understood by the team (that has to know the internals) and the users (who need to understand the use cases and the interface) is often very different.
Some advices
Grady Booch exposed in his book "Object Oriented Analysis and Design Technique", the content of a desired software documentation:
He further made a very specific point: