Documentation is like gift wrapping. It seems like superfluous fluff, but your family tends to be rather disappointed when their presents arrive in supermarket carrier bags, so you have to feign some sort of attempt at making your gift look enticing. Documentation doesn’t have to be all hard work and sellotaping yourself to a table – you can make it useful and relevant.
Documentation gets a pretty rough deal. It tends to get left until the end of a project, when some poor developer is assigned the ‘document project’ ticket and wades through each feature of Whizzy New API 3.0 and needs to recall exactly what each method is meant to do. That’s assuming any time is left for documentation at all. The more common outcome resembles last minute homework scribbled on a post-it note, where just the bare bones of what’s available are put out for your users, and you hope that you’ll spot the inconsistencies and mistakes before they do.
Wouldn’t it be nicer for everyone if you could make documentation not only outstanding for your users, but also a valuable tool for your development team – so much so that you couldn’t imagine writing a line of code before you’d documented it?
Documentation needs to have three main features:
- It should have total coverage and document all the features of your project. Private methods should be documented for your developers, and public features need to be available to your users.
- It should be consistent – a user should know what to expect from your documentation, and terminology should be accurate to your language.
- It should be current – and that means staying accurate as new versions of your code base are released.
But you can also get these bonuses:
- Act as a suggested specification – a guide that will aid a developer in making something consistent and usable.
- It can test your API quality.
- It can enhance the communication skills within your development team.
So how do we get our documentation to be rich and full of features, instead of a little worn out like Boxing Day leftovers?
Write your documentation first
When I say first, I mean first. Not after you’ve started writing the code. Not even after you’ve started writing your unit tests. First. You may or may not have been provided with a decent specification, but the first job should be to turn your requirements for a feature into documentation.
It works best when it takes the form of in-code comments. It works even better when your in-code comments take a standard documentation format that you can later use to generate published documentation for your users. This has the benefit of immediately making your docs as version controlled as your code-base, and it saves having to rewrite, copy or otherwise harass your docs into something legible later on.
Almost all languages have a self-documentation format these days. My choice of format for JavaScript is JSDocToolkit, and the sort of things I look for are the ability to specify private and public methods, full options object statements (opts as Opts only is a no-no), and the ability to include good examples.
So, our example for today will be a new festive feature for a JavaScript API. We’ve been asked to specify a sled for Santa to get around the world to give out toys:
Santa needs to be able to travel around the world in one night to deliver toys to children, and he’ll need some reindeer to pull his sled.
As documentation, it would look like:
/**
@name Sled
@extends Vehicle
@constructor
@description Create a new sled to send Santa around the world to deliver toys to good kids.
@param {Object} [opts] Options
@param {number} [opts.capacity='50'] Set the capacity of the sled
@param {string} [opts.pilot='santa'] The pilot of the sled.
@example
// Create a sled and specify some reindeer.
new Sled().reindeer(['Dasher', 'Dancer', 'Prancer', 'Vixen', 'Comet', 'Cupid']);
*/
By breaking it down as documentation, you can, for example, hand this over to another developer without the need to explain the feature in much depth, and they’ll develop something that has to match this piece of documentation. It specifies everything that is important to this feature – its default values and types, and where it inherits other features from.
We know that we need to specify some way of setting reindeer to pull the sled and also some toys to give, and so we can quickly specify extra methods for the sled:
/*
@name vehicle.Sled#reindeer
@function
@description Set the reindeer that will pull Santa's sled.
@param {string[]} reindeer A list of the reindeer.
@example
// specifying some reindeer
Sled().reindeer(['Dasher', 'Dancer', 'Rudolph', 'Vixen']);
*/
/*
@name vehicle.Sled#toys
@function
@description Add a list of toys and recipients to the Sled.
@param {Object[]} toys A list of toys and who will receive them.
@example
// Adding toys to the sled
Sled().toys([
{name:'Brian', toy:'Fire Engine'},
{name:'Drew', toy:'Roller-skates'},
{name:'Anna', toy:'Play-doh'},
...
]);
*/
Job done! You’ve got a specification to share with your team and something useful for your users in the form of full examples, and you didn’t even have to open another text editor.
Use your documentation to share knowledge
Documentation isn’t just for users. It’s also used by internal developers to explain what they’ve written and how it works. This is especially valuable where the team is large or the code-base sprawling.
So, returning to our example, the next step would be to share with the rest of the team (or at least a selection of the team if yours is large) what the documentation looks like. This is useful for two main reasons:
- They can see if they understand what the documentation says the feature will do. It’s best if they haven’t seen the requirement before. If your fellow developers can’t work out what ‘MagicMethodX’ is going to return from the docs, neither can your users.
- They can check that the feature accomplishes everything that they expect to, and that it’s consistent with the rest of the functionality.
On previous projects, we’ve taken to referring to this stage of the development process as the ‘bun fight’. It’s a chance for everyone to have an honest say and throw a few pies without actually causing anyone to have to rewrite any code. If you can identify at this stage that a feature is over-complicated, lacking or just plain useless, you’ll all be much happier to throw out a few lines of documentation than you may have been to throw out a partial, or even complete, piece of functionality.
Documentation has your back
The final benefit to working in this way is that your documentation not only remains accurate, it’s always as accurate as your latest release. It can’t fall behind. You can increase the likelihood that your docs will remain up to date by unit testing your examples.
Returning to the previous example, we can add a QUnit unit test to the expected output with ease during the build process – we know exactly how the code will look and, with the @example tag, we can identify easily where to find the bits that need testing. If it’s tested it’ll definitely work as you expect it to when a user copy and pastes it. You’re ensuring quality from idea to implementation.
As an extra bauble, the best thing about a system like JSDocToolkit is that it’ll take your inline comments and turn them into beautiful sites, as good systems will allow for customised output templates. You’ll be producing full-featured sites for your projects and plugins with almost no extra effort, but all the benefits.
Like what you read?
- Tweet this article
- or
- Leave a comment
Comments
Comments are ordered by helpfulness, as indicated by you. Help us pick out the gems and discourage asshattery by voting on notable comments.
Got something to add? You can leave a comment below.
11/12/2010
I don’t think inline documentation scales as well as we’d like it to.
For example, consider Ben Alman’s BBQ library It is littered with inline docs (for NaturalDocs) but he’s recently been reconsidering this decision to go with inline docs. It ends up making development a bit tougher.
I think APIs should be documented in HTML/Markdown/Wiki. It keeps the code clean and gives you plenty of flexibility to add examples, videos, whatever.
I do however, really enjoy the annotated source view that Docco provides.
I just did Modernizr’s source like this so you can take a look:
The annotated source of Modernizr
Vote Helpful or Unhelpful
11/12/2010
Very well put. In my latest JavaScript libray, named JSUF, I made use of the .doc attribute to attach comments and descriptions to the functions/method and created a built-in interactive API which can be activated at any time for debugging/developing. You select a function/method from the drop-down menu, click “Go!” and you’re prompted with a pop-up containing the description!
Vote Helpful or Unhelpful
11/12/2010
Another bonus you can get is type-hinting in an IDE.
Like Zend Studio Eclipse can give you hints while you type, so you don’t need go to the manual every time you need to use an function.
Vote Helpful or Unhelpful
11/12/2010
PAUL BENJAMIN IRISH:
This makes great sense, but I find that having inline doc comments allows for easier maintenance. Since the doc comment is easily accessed, I’m more willing to update it as I update the codebase.
Even with this ease, it’s hard to switch gears from formal logic to articulation. The author’s suggestion of writing first and coding second would help this issue.
Vote Helpful or Unhelpful
12/12/2010
I’m concerned that this article will mislead some developers into bad habits.
Writing documentation before tests for example is only sensible if that documentation is transitory, a token of conversation between you and your pair (I’ll take it as read you’re pair programming all the time).
Rather than documentation though, it’s often better to write Acceptance Criteria, something akin to Cucumber tests, and use those as your tokens of conversation. Test Driven Development latterly Behaviour Driven Development is all about ‘Growing Software Guided By Tests’, the design to your system emerges through those expressions of behaviour that compromise your test suite. Writing documentation up front, in the manner described in this article could easily lead to you pre-determining your implementation, which can result in YAGNIY, non-dry code.
Writing documentation for private methods is also contentious. Ideally you want internal code to be self documenting, in the way you write the method signatures and split up your responsibilities. Documentation on internal methods can dissuade developers from refactoring, something you absolutely don’t want to do. (Pairing, peer reviews and a good SCM system should ensure refactoring only have positive impact).
Documentation is definitely useful, the Rails and Django projects are great examples of where it’s proved how really valuable it is. Approach it wisely.
Vote Helpful or Unhelpful
13/12/2010
I do not agree with this article.
Ok, take the habit of properly documenting their code. But I remain convinced that good advice may not apply in a startup, to the limit in a large company where developers are paid handsomely and where we allocate more time than necessary for each task.
When your competitor is developing a project in the same time, you can’t afford to “lose” time, it’s just vital for the survival of the company.
Vote Helpful or Unhelpful
13/12/2010
I take issue with your comment Nicolas. If your startup ever wants to scale up the development team you will HAVE to have documentation.
I’ve been in the situation many times where 1 person does the bulk of the work on something and then you add person 2 and the process of handing off work to them is horrible because there’s no documentation.
Also, human memory is not perfect. If you stay out of a piece of code for a few months to work on something else and then come back to it… documentation will save your ass.
Vote Helpful or Unhelpful
13/12/2010
@Nicolas – Yeah, that’s possibly a fair point. I suppose the exact same concern can be turned around though. Can your start-up afford to write code that you need to throw away if you don’t take the time to identify if they’re useful features? Maybe your competitor creates a better API and documentation, even if they’re less feature-full, and “wins” because of that? I don’t consider writing documentation, or defining requirements and specifications to be “lost time”.
Horses for courses, though. I’m not suggesting this would work for everyone – but it’s worked for me and my colleagues before, in particular in the case where our ultimate goal was to create a public API that we expect users to be comfortable with.
Vote Helpful or Unhelpful
13/12/2010
Content is King & Documentation is Key
Sometimes API and web services that we take for granted and use everyday just stop working or have hiccups in their service that render the API useless.
Having some kind of system in place, whether through comments in the site code, or just having these functions be excluded from a page that is being loaded by using if/else statements.
When working within a design/dev team and more importantly within CMS, documentation is a most.
Vote Helpful or Unhelpful
14/12/2010
Great article highlighting the benefits of documentation.
I wholeheartedly agree that documentation is extremely helpful, especially if the product grows to a point where it has more than one or two developers working on it.
However I also agree with Nicholas’ comment. Having worked in a lean startup environment, if you are to stand any chance of success you need to move quickly. There’s no point in having detailed documentation for your code if that code never gets launched.
I have found that a compromise between the two works well. At Sonix Media we use agile-development techniques to a certain extent, but ensure that we spend time documenting the important areas. That way we get 80% of the benefit for 20% of the work.
I’ve found that a decent IDE such as PHPed is a great timesaver as its inbuilt commenting features and project support make really easy to add documentation whilst developing.
Vote Helpful or Unhelpful
14/12/2010
I don’t say it’s useless but if you really want to describe all functions like you do (params, examples, …), this will take a lot of time. In a startup environment, you sometime have to make radical decision in few hours and some functions can change or even be deleted.
Vote Helpful or Unhelpful
14/12/2010
I think Documentation-Driven Design works really well for Libraries and APIs as your documentation is part of your product.
In other situations, TDD & BDD can be a better approach as they have a big impact on the design of the interfaces and objects as Anthony mentions. Documentation should not necessarily come first in these scenarios.
As the title mentions though: Documentation-Driven Design for APIs. Maybe it should state public APIs?
Great article though Frances! Looking through the Glow source code is always a pleasure: easy to navigate and easy to figure out what’s going, which is not necessarily true for other well-known libraries. A tribute to DDD. Let’s hope it catches on :-).
Vote Helpful or Unhelpful
19/12/2010
@Nicolas sacrificing good practices to save time is like taking up smoking to lose weight. Short term gains reaping long term problems.
@gilles for public apis we should try and adopt an intuitive domain specific language. Eric Evans has written extensively on this topic in his book ‘Domain Driven Design’.
Vote Helpful or Unhelpful
03/01/2011
I believe there are several issues here that should spawn different conversations, namely:
1. Good API designs require good design documentation.
I have worked writing reference material and tutorials for very complex solutions that had poor design documents. Outcome: disaster. As an anecdote, developers leaving the team would leave information vacuums behind that no one could fill. Software improvement is based on comprehensive knowledge transmission. That is what documentation is for.
2. User documentation (programming references, for the matter) are integral to successful public APIs.
a. we defied some in-house developers working on other projects to a friendly programming contest, b. we gave developers the option to run their programming race with or without documentation: just that they had to choose before starting which path they would follow. Half of the developers then did not use documentation, the other half did so. Note: All six developers that entered the contested wanted to sit with the APIs documentation, but thisFor a project with some obstinate managers, we plot and executed a simple but insightful scheme:
of coursewas not enough to persuade our managers. So we asked half of the developers to go without the documentation, bribing them with a bigger price, which included chocolate chips.c. the games began. Each developer had to complete two tasks, one relatively simple (beginner level) and one relatively complex (expert level). The one condition: they had to use API calls to complete the tasks, without it being simple obfuscation.
Developers using the APIs reference documentation performed faster (completed the tasks in less time) and better (used higher-level API abstractions, specific for each task). A lot of other metrics where pointed out, such as better execution performance, neater coding style, fewer lines of code, etc.
I do not claim these are the most rigurous scientific data out there. Just that it convinced our managers, and that it points in some direction worth taking.
3. Documentation has a cost, as well as no documentation has a cost.
The most known cost-downsizing techniques in technical writing are shortening the amount of documentation, and reusing whatever documentation is written. Writing the documentation appropriately and precisely from the very very start is the only way to guarantee that less writing is taking place and most reuse will be attainable.
@Frances, you put your thumb where it hurts. And I love it!
@Anthony, you sound like a good manager. I just hope you had been in some of our projects! :)
Vote Helpful or Unhelpful
Impress us
Be friendly / use Textile