4 tips for writing documentation – Discoverable, Accessible, Searchable, Handleable (DASH)

Skipping the usual background rant 😛 For me, the purpose of documentation is to save time, not at the point of writing it, but in the future when you use it. When onboarding a new hire or answering a colleague’s questions on my code, I would usually first refer them to the README.md file in the root of my code repository. It definitely saves me from having to do a online meeting just to explain the architecture/workflow/installation/deployment/infrastructure for my code, over and over again.

I would like then, to share 4 tips for writing documentation, using the acronym DASH – Discoverable, Accessible, Searchable, Handleable. If applied well, people will dash to your documentation first whenever they have questions, instead of hounding you online and offline 😉 The context is focused mainly on handover, i.e. when a staff leaves the company.

D – Discoverable. This refers to how easily others can find your documentation without you telling them where it is, especially if you are not around.

• Do not just share the link to your documentation, especially for Google Drive files. Tell them where to find it, e.g. https://drive.google.com/drive/u/0/folders/abc123 - Google Drive for me@example.com > PUBLIC > Diagrams. Google G-Suite accounts are usually suspended/deleted after a staff leaves, with Google Drive folders lost or migrated elsewhere, hence the link may be changed/lost. By providing extra info on the owner of the documentation and the path to find it, others can trace back and find back the original file.
• For code repositories, follow the style of open source projects and ensure that there is a README.md (plain text file written in Markdown format) in the root of the repository. Other than this and CHANGELOG.md, all other documentation should be inside a docs folder in the repository and/or mentioned in the README. That way, if something is not covered in the README, others can just search the docs folder, instead of going thru all the folders and subfolders in the repository.
• If your documentation contains references to other documentation, ensure those references are discoverable as well. Don’t just share the link to the other documentation – tell others where to find it.

A – Accessible. This refers to whether others can access your documentation easily, especially after you have left.

• Documentation meant to be shared with the whole company, e.g. handover docs, should not be stored in your individual account (whether it be Google Drive or your laptop). Who’s going to give the new hire access to your documentation when you are gone?
• For those using Google Drive, either use Team Drive (only applies to the more expensive G Suite Business/Enterprise plans) which is like network shared drives, or use the Google Drive of a generic non-individual account that stays intact no matter how many staff leave, e.g. the Google Drive belonging to admin@your-company.com.
• If your documentation contains references to other documentation, ensure those references are accessible as well, especially if they are not owned by you. Imagine embedding a diagram in your documentation that was created by your ex-colleague – you may be able to view it but others may not have the permissions to view it.

S – Searchable. This refers to how easily others can find the information they need in your documentation, without you telling them which page/paragraph/line, especially if you start ignoring messages/calls upon your departure 😛

• Don’t write long narratives or tell grandfather stories. Go straight to the point.
• Split your documentation into sections. If a section is too large, move it to a separate file. For code repositories, try to have a similar structure for the README.md for all repositories so that others will be familiar with it and will know which section to jump to. Here’s a sample of the structure I usually use for the README:

  # Name of repository
  
  Do _**NOT**_ pass this document to clients as it is for internal reference only.
  
  Documentation meant for clients are found in the `docs` folder. All
  documentation should be written in plaintext files using the
  [Markdown](https://daringfireball.net/projects/markdown/syntax) format and
  follow the file naming convention `<DOC-NAME-IN-CAPS-AND-HYPHENS>.md`,
  e.g. `README.md` and `docs/USER-MANUAL.md`.
  
  Paths in all documentation, even those in subfolders, are relative to the root
  of the repository.
  
  ## References
  - This section contains references to things used for this repository, e.g.
  related repositories, user manuals, Bugsnag projects, AWS infrastructure, etc.
  
  ## Changelog
  - Refer to `CHANGELOG.md`. The one in the `develop` branch will always be the
    most updated.
  
  ## Requirements
  - [PHP](https://php.net/) >= 8.0.0
  - [Zend Framework / Laminas Project](https://framework.zend.com/) >= 3.0.0
  
  ## How do clients use this SDK?
  - See `docs/USER-MANUAL.md`. It is also published on ZenDesk.
  - Some things are not documented in the user manual as they are for our internal
    use.
  
  ## Installation
  - This section covers how to install/build/run/test the application on a
    machine, e.g. clone repo, set environment variables, composer install,
    etc.
  
  ## Deployment
  - This section covers how to deploy the application to production.
  - Deployment is done via Bitbucket Pipelines and is configured in
    `bitbucket-pipelines.yml`. See the docblock in that file for environment
    variables to set up such as AWS credentials.
  
  ## Infrastructure
  - This section covers how to setup the infrastructure for the application in
    production, e.g. on AWS.
  
  ## Workflow
  - This section covers how the application fits into the customer journey, and
    also the infrastructure journey (e.g. when user calls API at api.example.com,
    it hits AWS Route 53 > Akamai CDN distribution > AWS ALB > AWS ECS).
  
  ## Architecture Overview
  - This section covers the architecture of the application, including the
    directory structure. Diagrams can be drawn using http://asciiflow.com/ and
    included as plain text.
  
  ## Contributing guidelines for this repository
  - This section covers how to contribute to the repository.
  - References:
      + [Zend Framework Maintainers Guide]
        (https://github.com/zendframework/maintainers/blob/master/MAINTAINERS.md)
      + [Atlassian tutorial on Gitflow Workflow]
        (https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
      + [A successful Git branching model]
        (http://nvie.com/posts/a-successful-git-branching-model/)
  - Branches:
      + `master`: This branch contains the code deployed to production.
          * It MUST be releasable at all times.
          * Code should only be merged via pull requests. Do NOT push commits
            directly into this branch.
          * Versions are tagged against this branch.
      + `develop`: This branch contains new features and will become the next
        minor/major release.
          * The changelog, `CHANGELOG.md`, should only be updated via this branch,
            typically before a new release.
          * It is recommended that all documentation should be updated only via
            this branch, to prevent merge conflicts.
      

• If your documentation contains references to other documentation, ensure those references are searchable as well. If the other documentation is not written by you and the owner is still around, you can ask them to read this blog article 🙂

H – Handleable. I would have preferred the word “Handover-able”, but it’s not a valid word lol. This refers to how easily it is for others to handle your documentation, especially if you are no longer contactable, e.g. changed phone number, email, house.

• Use your Google Drive for your personal files only, not for shared documentation. As mentioned earlier, Google G-Suite accounts are usually suspended/deleted after a staff leaves. The administrator would not know which files/folders in your Google Drive are shared in other documentation, e.g. Atlassian Confluence pages. For the shared documentation, either embed the actual file as an attachment instead of just a link, or use a shared drive like Team Drive. Make life easier for the administrator.
• If you are doing a handover to another colleague, what happens to the documentation you wrote? If the colleague moves the documentation to his/her Google Drive, all the links that are referring to it will become invalid. If the colleague makes a copy, everything will be out of sync in time to come.
• If your documentation contains references to other documentation, ensure those references are handleable as well. Imagine embedding a diagram in your documentation that was created by your colleague, who leaves 3 months after your departure. If that colleague’s documentation is not handled well, your documentation will show a big blank 404 error 😛