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?

  • 1
    There is no "standard" or consensus what a "Software documentation" is (note your first link goes to a "Software design document", not "Software documentation", and is missing citations). There is also almost no standard what a "Technial documentation" shall contain (except it is often used to make a distintinction to "End user documentation"). – Doc Brown Jul 1 at 19:55
  • So I can choose freely which one I can use? I am more for the technical documentation since I have to do with a class library, it is not a software. – MrRobot Jul 1 at 19:57
  • 2
    Instead of overthinking the terms, think about what kind of documentation is required in your context / environment, what it needs to contain and who your audience is. How you the call the thing in the end is secondary. – Doc Brown Jul 1 at 19:59
  • @DocBrown I like it, thank you! – MrRobot Jul 1 at 20:03
  • Note also the term "Software" includes class libaries. You probably wanted to say you are not developing an application. – Doc Brown Jul 1 at 20:10

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:

  • Is it for new team members ? The most important thing is to give an overview (e.g. architecture and layers, main components), a high level domain model (i.e. context map), as well as some hands on information (e.g. directory structure, toolset used, naming convention, link to other important documents to read). The details will anyway be in the code be it in self-explanatory clean code or useful comments.
  • Is it for library users ? Your javadoc or doxygen will generate a suitable reference documentation based on comments that are embedded in your code (so hopefully easy to maintain). Unfortunately, this detailed information will not allow to understand easily the design of your library. Again, you need to provide some high level overview on the library's architecture, and how its different components interact and depend on each other. This kind of documentation is a MUST HAVE if your library is a commercial product sold on its own.

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:

  • High-level system architecture
  • Key abstractions and mechanisms in the architecture
  • Scenarios that illustrate the as-built behavior of key aspects of the system

He further made a very specific point:

It is far better to document these higher-level structures, which can be expressed in diagrams of the notation but have no direct linguistic expression in the programming language, and then refer developers to the interfaces of certain important classes for tactical details.

There are two basic kinds of documentation: user's guide and reference documentation.

(Some companies also recognize overview as a separate kind, see below.)


Reference documentation lists, diligently and accurately, the entirety of the product's public interface: what each switch and parameter means, what input is considered valid and what is returned in each case etc.

  • Note the word public interface: its primary goal is to specify which details of the observed behavior are officially guaranteed and thus can relied upon. (Stating or implying by omission that everything else is implementation details, subject to change and break without notice.)
  • Also note the word "entirety". The primary selling point of a reference is its completeness. If it's not in the reference, it doesn't (officially) exist. If I've read a reference on a topic, I can be sure that I now know everything on that topic and there'll be no nasty surprises.
    • So, even though a reference can be used as a learning material, its primary use case is to fill in the gaps.

Since design principles directly manifest themselves in the structure and organization of the public interface, a reference documentation can contain overview sections on parts and aspects of the product interface and behavior before listing their details (if only to avoid repeating them in entries for individual APIs).

  • Again, the focus is the public interface, so the explantions shall focus on the user-visible details critical to understanding the product's organization and behaviour, and technicalities not important for that can be omitted or hand-waved.

A User's guide purpose is rather to demonstrate how the product's authors envision using the public interface to solve practical problems and/or classes thereof: intended usage patterns, typical general problems and proposed solutions (problems local to specific APIs seem to rather belong in their reference entries).

A user's guide is intentionally incomplete, giving only the "big picture" and key pointers and leaving it up to the reference to elaborate on details.

User's guide can also have overview text, but the focus of the overview here is the usage patterns: what is supposed to be called after what, from what places etc.

  • note the word supposed. This is a recommendation: "This is the way that we intend to be the preferred one". What can (or cannot) be called from where outright is reference documentation domain.

Some companies, e.g. Microsoft, segregate the highest-level overview into a separate kind of documentation. In many place in MSDN, you would see a section on X divided into: "About X", "Using X" and "X reference".


As you can see, a user's guide and reference complement each other, cover different topics and explain things from different standpoints. Though the guide is more beneficial to the user in the short run while reference documentation in the long run.

  • Since reference is complete, it's "superior" to a user's guide in that any information that would be present in the latter can be inferred from it -- though at the cost of a steeper learning curve.

  • OTOH user's guide is much, much smaller and less taxing to maintain, especially if the interface changes quickly. The downside is your users never being sure if what they are trying to do other than the few examples you gave is supposed to work or not, what syntax is permitted where etc -- resulting in massive waste of their time.

man pages are a classic example of reference documentation. Some man page authors (e.g. rsync) tried to add user's guide sections -- and by doing that made it harder to find the necessary reference sections.

Your Answer

 

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.