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!

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.

@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.

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

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.

PAUL BENJAMIN IRISH:

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.

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.

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.

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.

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.

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.

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.

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 :-).

@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’.

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.
For a project with some obstinate managers, we plot and executed a simple but insightful scheme:

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 this of course was 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! :)