You’re working on a software project, probably not a new situation if you’re reading this, and happen upon specific functionality you need for your project. Being the efficient (and lazy) developer that you are, you recognize that this functionality is general enough that it’s probably been needed by someone before and a library of some sort has been written for it. Why reinvent the wheel?
So you jump on your preferred search engine, find a likely candidate, skim over the landing page, and conclude that this library meets your requirements. You then locate a link to documentation and click it. After all, you need to figure out how to install it, configure it, and actually start using it in your project. There’s just one problem: the page linked to by the documentation link contains nothing but generated API documentation. You immediately think: where do I start?
You may take a step back, search the version control repository, and find a file named something like README, INSTALL, or maybe even EXAMPLE that gives you a smidgen of information on what to do next. Even if you manage to get the library installed and configured, where do you go from there? Which specific piece of code provides an entry point into the library’s logic? Do you need to do something specific to load or bootstrap it? Is there anything else you need to do before using it aside from dropping it into your project’s directory structure and changing a few configuration settings?
You may fumble around for a short time, scanning the API docs for information more substantial than names of classes and methods or types of parameters and return values. You may make educated guesses and try things just to get a foothold into getting the library to work. If you’re unsuccessful, a point will come where you’ll throw your hands in the air and move on to the next option.
If you’re writing code that will be shared with others, put yourself in their shoes. Don’t let your project lose potential users, community members, and possible contributors all because of insufficient documentation.
Content is King
“Content is king” is a predominant principle in SEO (search engine optimization). The same applies to your documentation: it has to be chock-full of information with common use cases, example code, warnings about potential pitfalls, and so forth. Sadly, rubber ducking isn’t as effective as it is with debugging because the duck provides no feedback and this isn’t the type of problem where solutions are very likely to be revealed in your explanations.
Make a first attempt at what you believe is good documentation and then do what all good developers do: beta test it. Have several people read it, try to use the library, and provide feedback. Ask them what parts weren’t clear or could be stated or organized in a better way, where information was lacking, what additional information might have been useful, etc. Iteratively apply improvements prior to your project’s launch so that most potential issues are resolved beforehand or soon afterward.
Open It Up
Cranking out quality content is a lot of work, especially in the beginning, but it’s also a large part of what attracts early adopters. Once a project is off the ground, people may be willing to contribute to documentation if they don’t have time or skills to commit to the source code. If they don’t have a way to get changes to you, though, it can be very off-putting to contributions. You don’t want that.
There are two major methods of opening up documentation to help your users help you keep it current and sufficient for their needs: using a wiki or maintaining it in a version control repository.
Wikis like DokuWiki, MediaWiki, and (for larger companies) Atlassian Confluence are generally easy to set up and customize to suit your needs. You can allow anyone to edit them or require users to register first. Most wikis maintain a version history of each page, allowing users to revert malicious changes and review who made a revision and why it was made. There may be a slight learning curve with regard how to use the wiki, but browser-based interfaces are otherwise very accessible for prospective contributors.
Using a version control repository allows documentation to be maintained right along side your source code. Experimental branches with additions or changes can easily be shared and reviewed by peers before being merged. Interfaces like those provided by GitHub can make tracking proposed contributions easy while limiting changes to a select number of contributors with merge rights to maintain quality assurance. Depending on the format and tool chain you choose (like Docbook and PhD for example), it’s also likely to be easier to make your documentation available in multiple formats like HTML, PDF, or ePub and integrate documentation into your build and continuous integration processes.
Whatever documentation you do make available should also be as accessible as possible. Don’t require a user to go through a registration process to access it. Host a public text or HTML copy for users to access in a browser rather than requiring them to download it in its entirety to view in a separate program. This has the added bonus of enabling search engines to index it. Make sections in HTML copies linkable using anchors to allow users to easily reference them individually.
Documentation, Documentation, Documentation
Steve Ballmer has become rather infamous for his “Developers, developers, developers” chant. This is, after all, representative of what people who begin software projects generally want: a community of developers to form around that project, contribute to it, and help to evolve it and make it better than you could alone. While it’s not the only means to that end, documentation is very unlikely to hinder you in that goal if it’s good and well thought-out.
Make it a point to seek out technical writing resources to help your documentation authoring skills. Such resources exist in many forms like a course at your local university, posts in Kathy Sierra’s now-defunct Creating Passionate Users blog, the “Communicate!” section of the book The Pragmatic Programmer, the Missing Manual author guidelines, and Rich Bowen’s presentation Write a Better FM. They may also come in less obvious forms like Garr Reynold’s book Presentation Zen, which covers creating provocative visual presentations – regardless of the end medium, the book teaches you how to present information in ways that make it interesting and informative to its consumer.
Summary
In short, make a substantial effort to document your project and make it usable for others. It might surprise you how much more support you receive in development simply because you put in that time and effort. Regardless, it will be time and effort well spent.
Matt TurlandMatthew Turland has been working with PHP since 2002. He has been both an author and technical editor for php|architect Magazine, spoken at multiple conferences including Confoo and php|tek, served as an instructor for php|architect training courses, and contributed to Zend Framework. He holds the PHP 5 and Zend Framework ZCE certifications and is the author of "php|architect's Guide to Web Scraping with PHP." He currently works as a Senior Engineer for Synacor. In his spare time, Matt likes to bend PHP to his will to scrape web pages and run IRC bots.
