Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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)

share|improve this question
2  
Comments on downotes always appreciated. Unfortunately numbers don't provide much constructive criticism to understand where one has strayed :) –  Dan McGrath May 16 '12 at 5:01
1  
Software documentation or source code documentation is written text that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles. - The "may mean different things to people in different roles" is the key sentence here, what's your audience? (Haven't voted yet, but I'm guessing the vagueness and open ended nature of the question is to blame). –  Yannis Rizos May 16 '12 at 5:03
    
Related: Are Comments a form of Documentation –  Dynamic May 16 '12 at 9:48
2  
This question is screaming for someone to draw a Venn diagram. –  MathAttack May 16 '12 at 11:14

4 Answers 4

up vote 6 down vote accepted

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.

share|improve this answer
    
I'd only consider course materials to be documentation if they are being produced/distributed by the same team (in a broad sense) as produced the software. Totally third-party courses aren't docs. –  Donal Fellows May 21 '12 at 20:10
    
Of course they are. Third-party documentation is documentation even though it isn't under your control (and isn't your responsibility to produce): it serves the reader's goal of explaining the stuff to them. If it's a problem to you that people are writing documentation that isn't under your control, you should obviate the need for that documentation. –  user4051 May 22 '12 at 0:34

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.
share|improve this answer
    
Saying I took the wrong part of the conversation based upon a single Q is a bit much of a conclusion to draw from one Q :) I'm new at this company and helping out with improvements. Giving our 'customers' number in the 10'000s+ of developers (we write databases) negotiating with them all is a bit hard (although, I try - running focus groups, advisory boards , etc). I don't disagree with your answer, but I was just looking for what could be/isn't consider documentation for this one part of the conversation so I can have a data point to start from that isn't merely my own opinion. –  Dan McGrath May 16 '12 at 12:38
    
@DanMcGrath: sorry, I do tend to rub PMs, including my own, the wrong way :) Regardless of the assumed conclusion that I drew from your Q, I would still maintain that "anything" that goes along with the code can be considered "documentation". If I were you, instead of asking "what can be documentation" and compiling a comprehensive list of all kinds of things (I used to have a reference napkin with a UML diagram on it), I would go back to my customer base and ask them what they need. If nobody says "I want a video tutorial", why would I spend any brain cycles even considering that? –  DXM May 17 '12 at 1:44
    
No problem DXM. I'm only a new PM too, only recently shaving my coding chops off (partially). I was more so interested to see if someone came back with something I hadn't considered either as a concept or as an artifact to consider. I'm a big fan of asking 'what is your problem' and having our team work it out collaboratively with the customers, as opposed to asking 'what do you want us to do'. Along the same lines as ['We want to move faster'->We build cars] vs ['We want you to give us faster horses']. Having us much info at hand helps collectively finding the best solution more likely. –  Dan McGrath May 17 '12 at 2:27

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.

share|improve this answer

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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