In this article we’ll cover:
- Why documentation is important
- Whom documentation is for
- What to include in your documentation
- Methodology
Why is documentation important?
Documentation helps users understand how a code works—it’s like a layperson cheat sheet for what was going through the developer’s mind when she coded it and how to most effectively use the code. It can also help teams of coders create a shared terminology for a certain project they’re working on as a group, and it can even help the coder herself to remember certain shortcuts and tips as she writes her own code, in case she loses track.
Now that we know why documentation is important, let’s explore the audience for which we’re writing our documentation and how that shapes the way we do it.
Whom is documentation for?
While documentation can just be for personal use or for use among a group of coders, it will still eventually be used to help the client or user understand how the code works, and for that reason it should be kept as simple as possible. That being said, you want to be thorough and leave nothing unexplained. What follows are the key components to include in your documentation.
What should I include in my documentation?
1. Style guide: explain the linguistic customs and etiquette for the content being written on the site—not only mechanics and usage but any spellings or phrasings particular to the content on the site. Include recommendations for how often to update the content.
2. Navigation guide: explain the fields and taxonomies that connect the different types of content on the site.
3. Technical specs: list specifications for multimedia and images—including preferred formats, sizing and optimization.
4. Templates: enumerate each kind of template available on your site, including any templates for microsites.
5. Pages: explain how to manage the pages, point out any pages that break the rules, and list the available components for creating each page (e.g. call-to-action buttons, galleries, etc.).
6. Any additional website components needed, such as: visual examples, recommended character counts for various elements, page designations for each component, and code examples.
7. Branding guidelines: color palette, logo variations and how they should be used, iconography.
How should I structure my documentation?
1. Make it easy to understand: always go back tothe notion that you are writing this for a non-coder. Think of every line of documentation from a layperson’s perspective and ask yourself if it makes sense. Better yet, have a non-coder look at your documentation to see how successful you were.
2. Write a short and helpful abstract at the beginning: briefly explain why you created this code, for whom, what its intended purpose is, and its key features, so readers can quickly ascertain how the code is relevant to them and their needs. Point out any dependencies that exist with other features as well.
3. Use the standard of the language: Describe each function, the variable, and value returned by the function according to the coding language you are using.
4. Use graphical elements: many people are visual learners, so using different kinds of information can be invaluable to some, and if you’re using graphics in your code, this makes a lot of sense anyway.
5. Split it into sections and use helpful headers: this way readers can scan through the documentation and get to the specific information they need as quickly as possible.
6. Update it consistently: the code will change as you work out bugs, so make sure your documentation reflects that.
7. Include a timestamp and any libraries you’re using: this verifies that your code is valid and up-to-date.
8. Make your content accessible: there are laws governing how to make web content accessible to users. Familiarize yourself with the proper protocols. Here is a good place to start.
9. Use lots of examples: clear examples of how to use each feature and the expected end result will help users further understand your code.
And speaking of examples, here are some samples of good documentation that we like:
Mozilla: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
Django: https://docs.djangoproject.com/en/2.0/
Stripe: https://stripe.com/docs
Follow these guidelines, and you will have flawless documentation at your fingertips in no time.