When you hear the word documentation, if the first image that pops into your head is the crummy user guide you just threw away, you are in for a surprise. In the hands of Alex Lyte, John Griffith, Tod Levitt, and Leo Obrst, documentation is an indispensable business asset that reduces the cost of software and greatly improves user experience. And, if you are a developer, makes you an excellent ancestor. –Editor

Authors: Alex Lyte, John Griffith, Tod Levitt, and Leo Obrst

By having documentation dependent on volunteers and code developers, documentation updates lagged behind the evolving system software. As significant development changes were made to the system, existing documentation became dated, and its value significantly reduced. The valiant efforts that were made to keep the documentation current proved too difficult as changes to the system sometimes had far-reaching effects on pages throughout the documentation. System integration and optimization quickly rendered documentation obsolete for developers. The code became the substitute and source for documentation. – OpenACS Documentation History

Software development and documentation do not always go hand-in-hand. There are not always clear incentives to document how software works and what it does, especially in the face of deadlines, ambiguous user groups, and proprietary concerns. But documentation improves adoption of software, and in an era of collaborative development and platform-driven business models, increasing the number of users is key. To address the challenges of documentation, a number of social norms, tools, and techniques have emerged, barriers to good documentation are falling, and a software economy has formed with ease-of-use and interoperability as its main drivers.

From Source Code to Spoken Word

READMEs, inline comments, and the source code itself have always been acceptable for developers. Large paper manuals were produced for end users for many years, but quickly become out-of-date after each update. New tools, such as Doxygen, were created to automatically document code, providing information similar to Man Pages on the input and outputs of each function. As the Internet became the main publishing platform for software, a more community-driven documentation culture emerged. Developers now write and share code on many sites, such as SourceForge and Google Code. GitHub has become one of the most popular open- and closed-source code sharing platforms on the Internet, in part because of their emphasis on READMEs written with standards and markdown, Wikis, and issue tracking integration. However, many developers simply use Question & Answer sites like StackOverflow to get examples of specific usage of software. Both GitHub and StackOverflow use metadata to categorize software, including the programming languages, licenses, and other keywords. Using metadata, software users are able to quickly identify software that fits their needs, making it easier to build larger, more modular software products quickly.

Many programming languages, such as NodeJS and Ruby, have combined modular package management with vast development communities to make plug-and-play development fast and easy. Furthermore, advances in machine learning and natural language processing allow documentation to be linked semantically, forming models or partial models to solve problems. Often, documentation can be helpful for defining what code does before the code is written. Development teams use wireframes, architectures, and other descriptive documents to define exactly how a system works, translating from the idea down to the code.

One design paradigm, literate programming, begins with writing a process in ordinary human language and then translates into computable form. When done up-front, this type of documentation can help translate the idea from the business team to the developer, allowing for greater shared understanding of the idea. Complex problems often require translation between many languages, both human and machine, to enable systems to work effectively.

In Sum

Software is part of our everyday lives, and has helped solve problems both large and small. As demand for software grows, so does the market. With more people producing software, the development communities have improved methods of sharing and collaboration. Sites devoted to documentation and learning, including MSDN, MDN, and W3Schools, have greatly increased access to information, which indirectly increases the quality of code produced by all developers. A code-sharing economy has emerged online—the so-called Open-Source movement, which has made the cost of software virtually free. This has turned the “learning curve” into the driving cost of adopting new software. Since documentation greatly increases the understandability of software, it has become a very valuable asset in the software market.

So ask yourself, do you need to document your code?