Motivation & Best Practices

xkcd 1343: Manuals

Why We Document

For others: Because you want to transfer knowledge.

For yourself: Because future you would like to know what past you was thinking.

From Write the Docs' "A beginner’s guide to writing documentation":

  1. You will be using your (project) in 6 months
  2. You want people to use your (project)
  3. You want people to help out
  4. You want your (project) to be better

How to Document

"It doesn’t matter how good your project is, because if the documentation is not good enough, people will not use it."

Good documentation enables people to use your work effectively and in the ways you intended. When writing documentation, it can be helpful to think about the functions it needs to support. In the case of software, Daniele Procida argues for four kinds of documentation types: tutorials, how to guides, reference, and explanation, but this framework can be helpful for thinking about documentation for all kinds of projects.

Tutorials: Lessons that allow a newcomer to get started.

How to Guides: Series of steps that shows how to address a specific problem or task.

Reference: Information about the attributes and methods of project, often technical in nature.

Explanation: Background information that broadens the project's documentation.

Hands-on: Workshop software setup

We will be using the readthedocs.org platform as a way to easily publish a documentation website. It focuses on programming and code documentation, but the service can be used for hosting any kind of non-commercial documentation you like for free.

  1. Download & Install Visual Studio Code
  2. Download & Install GitHub Desktop
  3. Sign up for a GitHub account
  4. Sign up for a Read the Docs account using your GitHub account

Discussion: What motivates your documentation?

What reasons can you think of for making documentation that we haven't talked about?