I have always thought that documentation was a vital component of any FOSS project. But recently the value of documentation was illuminated for me in a new way. This has me rethinking the basis of the importance of documentation for a FOSS project at nearly any stage of development.

Let me describe the case that prompts this reflection. A long-term (2 to 3 year) user of an enterprise software deployment recently announced, with regret, on a user/developer list for that software that the decision had been made to migrate to an alternate enterprise software solution. The reason given was that the documentation of the software currently in use was not comparable in quality or comprehensiveness to its competitor. Both, clearly, met other technical functional requirements for this user. But the discrepancy in the documentation was a deciding factor in the decision to migrate away.

What struck me was that this user was willing to accept the change cost of an enterprise level migration because of documentation.

That is remarkable. And it speaks volumes about the value of documentation.

Documentation - it's quality, comprehensiveness, easy of use (for different audiences), and coherence - is a key criteria I would use for determining whether to choose any enterprise software solution. It is, I would argue, part of the functional aspect of enterprise software deployment. And here I make no distinction between proprietary or FOSS alternatives; in either case solid documentation is not just window dressing, it is an integral part of the package you are selecting.

Software that isn't merely for my personal use, that will have a multitude of users, and potentially a wide range of people other than me maintaining that use behind the scenes is what I'm loosely calling enterprise software. In such cases it is very likely that the person who installs the software may not be the person who maintains it, and that person will probably not be the same as the people who use the full functionality of the software, and even these people may be intermediaries with the real end users further down the chain of use. Examples of such software will spring quickly to mind for academic and library staff, e.g. your learning management system (LMS), your integrated library system (ILS), your content management system (CMS), and even your student record system. All of these would qualify as enterprise level software deployments under my characterisation. And it is these cases where I am claiming that documentation is part of the functional aspect of the software deployment.

By contrast consumer software - software that a single user can typically download and install directly - does not need to treat documentation as part of its functional aspect. I don't usually need to think about the documentation in order to choose to use this software and almost certainly it won't be the quality of documentation that keeps me using it in future. (This, by the way, is not a comment about the importance of documentation for a FOSS development community working on consumer software.) Of course there are some consumer software products that are so complex that I may need substantial end-user documentation. But let's move on.

Documentation is famously what developers least like to work on. Not all of them, obviously, but generally speaking. This could be because it is a special form of tedium to explain the blatantly obvious to the complete beginner. Imagine someone with a Ph.D. in mathematics called upon to teach addition to children. It could also be because software code itself is written in a language that can be read (and with FOSS also easily accessed), and thus any well-written code (with sufficient comments included as pointers ) should be its own documentation.

There are other reasons why documentation might not be at the top of the list for a project. In no particular order:

• the project is at a very early phase in which the code itself is changing rapidly (and it is easy to convince ourselves that documentation ought only to apply to code that is stable);
• the software is exceedingly technical and so the installation instructions alone are likely to be sufficient for anyone capable of using it;
• the software is exceedingly easy to install and most users find its use fairly intuitive;
• the development team has tight deadlines and cannot afford to take time away for documentation writing;
• this is FOSS and I (the developer) am scratching my own itch (for the software) - if you have an itch for documentation you should write it yourself;
• a documentation effort was started but ran out of steam and now the software has moved on;
• it turns out writing cogent explanatory text for a range of audiences is a different skill than writing clean code (despite the requirement that code needs to be readable at least by other programmers).

It's not a complete list by any means, but it probably covers a fair number of cases.

However, if we begin with the assumption that, at least for enterprise software deployments, documentation is a functional aspect of the deployment, then the above rationalisations lose persuasive force. Enterprise solutions always involve more people than just the developer. Communicating everything from the installation procedure to basic configuration to full use is going to have to be part of what makes the software an enterprise solution in the first place. So, far from being a mere addendum to the software, documentation needs to be seen as crucial to a completed solution.

There are consequences to thinking this way. How often have you seen an official release (not merely a release candidate) of enterprise level software that did not have complete documentation accompanying it? How often have you seen software products whose documentation is significantly out of date or incomplete? How often is getting that next feature into the software more important than documenting how it changes things?

If documentation were really a functional aspect of enterprise software, then its drafting, careful editing, and appropriate quality assurance processes for it would be part of the release cycle of the software. That in many cases it isn't only shows that we have more work to do.

As I noted at the start, I have been prompted to rethink the basis of the importance of  documentation for a FOSS project. I'm still thinking through the implications. But I do know one thing for certain. There is almost no greater service you could render a FOSS project you care about than to help them with their documentation. Get involved, do it early, and help to make comprehensive documentation part of the release cycle for your favourite enterprise level FOSS solution.