A quick start guide describes how to get up and running

This is the traditional “Hello world” example that many libraries have. A good quick start guide describes how to obtain and set up the library, and how to start using the functionality immediately. Twitter Bootstrap has a great getting started guide

There are common use cases that library users frequently need and so it’s important to show them how to complete those tasks. The tutorials should be in narrative form, describing each step of the process and resulting in a functional prototype at the end. jQuery has a large amount of tutorials13 that are very well written.

If you offer an API for others to use, then API documentation is very important. This describes every public interface of the API in very fine detail, including the names of functions, the types of arguments the functions expect, return values, available classes, and more. The YUI library has an excellent and fully searchable set of API documentation

Design documents describe the architecture and options available within some piece of software. It is frequently written before coding begins and updated once coding is complete. Design documents answer the question, “How does this work?” It’s quite common to see diagrams as well as discussions around design philosophy, design patterns used, and assumptions the software makes.

Chromium, the open-source project on which Google Chrome and Opera are based, has an excellent set of design documents15. When you inherit some code that you must begin to maintain, the design document for that code should be the first place you go to get a good understanding of the code.

In general, getting started guides and tutorials are necessary when you’re creating a library for others to use. API documentation and design documents are good regardless of the software you’re writing. The exact structure of these documents necessarily varies based on the software you’re creating and the intended audience.

Lastly comment

API documentation is the minimum that a project should have for documentation. Most languages, including JavaScript and CSS, have tools for generating documentation from the source code. These documentation generators use comments embedded within the code to create standalone documentation (typically in HTML format) describing the code. The exact comment style depends on the tool being used. Here are some tools worth investigating:


Related Articles

Back to top button