Skip to content

Instantly share code, notes, and snippets.

@inadeqtfuturs
Last active April 8, 2023 13:11
Show Gist options
  • Save inadeqtfuturs/46466d91ce9ea048c87172631c5ed8c3 to your computer and use it in GitHub Desktop.
Save inadeqtfuturs/46466d91ce9ea048c87172631c5ed8c3 to your computer and use it in GitHub Desktop.
opinionated docs
title
opinionated documentation

Opinionated Documentation

This guide outlines some principles for writing internal documentation. The scope of this guide is narrow and is adapatable depending on the project and team size.

Consider the reader

The reader is most often going to be another developer. Because of that, we can assume some level of familiarity with the code base, language/framework, or service we're writing documentation for. Consider some of the following when writing:

  • Opt for explicit instructions rather than implicit. I.e. tell the reader exactly what to code. Tell them what to click in the service you're writing about.
  • Provide copy and paste-able code blocks.
  • Explicitly reference files that need to be updated or that stand as an example of what is being documented.
  • Docs should be skimmable/scannable, so opt for descriptive headings and clear topic/introductory sentences.
  • File names and topics should be easy to find by looking at file names and/or greping the docs folder.

Write Consistently

The documentation should be consistent with the rest of the documentation in the repo. That is, it should follow a similar format (see below) and voice of other pieces of documentation. Just as we have a consistent code style within the repo, we should have a consistent documentation style within the repo.

In general, write with a neutral tone and/or the tone consistent with the documentation in the repo.

Instruction vs. Explanation

Docs can take two (of many) shapes: instructive and explanatory. Instructive docs tell a dev what to do to implement a feature, like adding a new slice to redux. Explanatory docs explain why a codebase, process, file, or function is written or how it works. Docs are often a combination of the two, but it's usually best to separate instuctions from explanations.

In the following example, we provide a few things:

  1. A brief overview of the feature/thing we're talking about
  2. Explicit step-by-step instructions for implementing/working with the thing
  3. An explanation of why we've opted to do it this way
  4. (Optional) A list of resources related to the thing if the reader is unfamiliar

Examples

# Topic

## Subtopic

Brief explanation of what subtopic is

1. Instructions
2. For implementing
3. Subtopic

Brief explanation of why we've decided to implement feature or whatever this way.

## Resources

- [Resource](link)
- [Resource](link)
- [Resource](link)

Breaking Down a Topic

Depending on what you're documenting or the size of the codebase, a flat list of markdown files might not be the best form for documentation. Consider the following:

  • Are you documenting something isolated and singular, or something that's part of a larger system? A folder might house multiple pieces of documentation about a system or a topic that has many discrete parts. An example might be a "State Management" folder with separate files for things like reducers, actions, hooks, and how the codebase tends to structure state.
  • When a single file gets too long (hundreds of lines), it might be time to rethink its structure and break it into multiple files. The headings in the original file are helpful for creating the new files.
  • Use relative links to link between documents.

Formatting

  • Use properly formatted markdown.
  • Provide a semantic and skimmable hierarchy of information by using headings.
  • Use lists for instructions. Numbered lists are good for sequences, whereas unordered lists are good for general tips/suggestions.
  • Add a single white space between semantic elements in the markdown.

Resources

@EllieSadler
Copy link

As someone who loves to write and read easily skimmable and instructional docs (especially w/ code snippet examples), those guidelines look good to me.

  • No need to include your personality in it. It's instructional documentation not an article on a website.
  • Headlines make things easily skimmable.
  • Don't be afraid to break things out into separate files to keep things organized and easy to find.
  • Be aware of config options that should be called out for the function, hook, etc. that you're documenting.
  • Referencing the file location for what you're talking about can be helpful for something not easily findable or in a low traffic folder.

@inadeqtfuturs
Copy link
Author

Thanks, @EllieSadler. I'm going to add these

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment