What exactly comprises 'Documentation'?

Question

When we say 'documentation' for a software product, what does that include and what shouldn't that include?

For example, a recent question asked if comments are considered documentation?

But there are many other areas that this is a valid question for as well, some more obvious than others:

• Manuals (obviously)
• Release notes?
• Tutorials
• Comments
• Any others?

Where is the line drawn. For example, if 'tutorial' is documentation, is 'video tutorial' documentation, or is it something else?

Generally, something in software isn't 'done' until it is implemented, tested and documented. Hence this question, what things should we consider as part of documention to consider something 'done'.

---

_{Question inspire from recent customer feedback at our conference indicating that our doc needed more 'samples', which we previously hadn't been as good at considering as we should have been.}

_{Audience: Software developers using our database(s), programming languages and associated tooling (such as admin clients to said DB)}

Answer 1

The goal of documentation is to describe and explain the software product, so you could define the documentation to be the set of artefacts that contribute to that description or explanation. You'd probably not consider related actions as part of the documentation: e.g. a week-long training course is not documentation but the course materials are; a five-minute whiteboard chat is not documentation but an image of the whiteboard is.

Keeping the goal (explaining the software) in mind, the documentation is finished when the customer is satisfied with the explanation: just as the software is finished when the customer is satisfied with the software. Bear in mind that the customer for the documentation is not always the same as the customer paying for the software: support personnel, testers, salespeople and others will all need some understanding of what the software does and how it works.

This helps understand where your boundary for what should be included in the documentation lies. Using "reader" as a convenient shorthand, though we accept that videos or audio could be included: anything that helps the reader gain the information they need about the software is documentation they can use, everything else isn't. If your customer needs detailed walk-throughs of all their use cases, then that needs to be part of the documentation. Your developers probably need source code, information about your version control repository and build instructions: that's documentation for them, but as described above it wouldn't be part of the customer's documentation.

Answer 2

I think you took away the wrong part from your conversation at a conference. Modern software development methodologies advocate that the development team should be working closely with its customers (or a product owner who's acting as a customer proxy). For all work delivered, definition of "done" is something that is negotiated between the team and its customer and is done on recurring basis as the software is being developed.

The problem you ran into is that you had a disconnect between what you assumed the customer needed and what they expected you to deliver so at the end you got the "hey where are all the samples" surprise.

As far as, what is documentation... well, it's pretty much everything you listed and maybe few more things that you didn't. But nobody can tell you how much documentation your project needs. Every project is different and it is up to your team, your product owner and your customers to determine the level and type of documentation that is required for your project.

Some factors that would come into play:

• Are you developing software v1.0 and them moving on to other projects or is this on-going, long term project? Comments/design docs become much more important in the latter case. On the other hand if your customer is a mom-and-pop donut shop and you are writing a website for them that you will never see... well I guess code documentation is nice but not that important.
• Are you developing an mobile game or software that is controlling heart rate monitor in a hospital. Guess which one will have definition of "done" that has much more documentation?
• Are your customers typical end-users or are they other developers? Do you have an API/SDK that you are exposing?
• What is the level of expertise of your customers? This affects the choice of video tutorial vs. written material vs. some kind of interactive tutorial app
• Do your customers care about what changed from version to version. Some do. Most don't. For few it's the law (or close to that) to care.

Answer 3

Documentation is stuff intended to be read without modifying it.

I think you can't go wrong with purpose-based definition... but only if you define purpose properly.

• ^{Properly defining documentation purpose is not quite simple. Straightforward (naive if you wish) distinction that naturally comes to mind is that documentation is everything that is intended for reading - while, for comparison, code is anything intended for computer execution. Sounds nice at the surface doesn't it? but it really turns out quite ugly once you dig deeper.
   
  Thing is, good code takes into account readability concerns, along with execution correctness - this makes "readability" distinction pretty useless in defining documentation.
   
  The very samples you mentioned show what's wrong with it. Clients typically expect these to be clearly written and execute correctly. Compromising either of readability or correctness can bring a waterfall of the customer complaints. Naive distinction doesn't help to figure whether samples are code or documentation.
   
  Using naive distinction will get even more messy if you imagine working with open source. You download, build and run it - you don't read it, it's just the code right? Wait, things somehow went wrong and you get to the code to read what's going on there... hey you read not execute - is this documentation now? And, finally, you find bug in the source and fix it - now this is really the code, it is not something normally called documentation, no matter how carefully you read it to make that fix.}

For the 'samples' you are going to provide, read-not-modify distinction might turn out quite important.

Look, if some sample fails when run unchanged, in the documented reference environment, it's your bug - bug in your documentation, one you have to accept and fix, fine.

Now, if there is a problem with modified sample or environment, it's not your fault anymore - I mean no bug in the documentation, since docs are not intended for modification. Whatever help you provide users in case like that, would fall under support category, not a bugfix.

Answer 4

Anything that answers a "how do I..." question is documentation.

For developers, that means requirements specifications ("how do I know what to write"), design documents ("how do I address my requirements"), traceability matrices ("how do I know that my designed addresses all my requirements"), test plans ("how do I know my code works"), unit tests ("how do I know I've safisfied requirement X"), inline comments ("how do I make sure the next poor schlub understands why I wrote it this way"), deployment instructions ("how do I package this product for installation"), etc.

For users, that means user manuals ("how do I use the software"), tutorials ("how do I use this specific feature"), release notes ("how do I know what bugs have been fixed/new bugs features have been added"), etc.