Welcome!
This playbook walks you through a method for creating documentation for your software project. It hits all of the items on the One Good Tutorial Checklist.
The playbook is delivered as a slide deck. Navigate using the buttons in the lower-right, the arrow keys on your keyboard, or swipe gestures.
Part 0: Preliminaries
A few points to address before we really get started.
Intended Audience (1)
This playbook is aimed at authors of small, DIY-style software projects. We’d like to think that it will still have something to offer to participants in larger, more formalized projects, but to keep things focused we’ve avoided even mentioning some of the challenges that arise in bigger efforts.
Intended Audience (2)
This playbook is also aimed at authors of scientific software projects. We talk about a few issues, like citation, that other kinds of projects may not be concerned with. But most steps will be relevant to virtually any kind of software.
Terminology
We assume that your documentation will be eventually published as HTML on the web, so we’ll refer to documentation pages and your overall documentation site. Reinterpret accordingly if you’re targeting a different medium.
(Arguably, writing docs in the 21st century requires you to become a bit of a web developer. Fortunately, hosting services like ReadTheDocs.org can take care of a lot of the hard parts for you.)
The Prime Directive
Above all else: this playbook is a recommendation, nothing more. Take inspiration from the parts that you like, ignore the ones that you don’t, and always trust your intuition. There’s no one “right” way to write docs, any more than there’s one right way to do anything else creative.
Part 1: Planning
“Plans are worthless, but planning is everything.” — Dwight Eisenhower*
Step 1: Start A Notes Doc
It’ll be helpful to have some place to write down notes as you work on your docs — no need for these to be public. A Google Doc is fine. So is paper!
Step 2: Draft Your Synopsis
The synopsis is 1–3 sentences summarizing your software. Jot down a first draft in your notes.
Example: “FiPy is an object oriented, partial differential equation (PDE) solver, written in Python, based on a standard finite volume (FV) approach."
Why: Your final synopsis will end up everywhere: at the top of your README or website, in announcements, maybe even grant proposals. Best to get a rough draft ASAP.
Step 3: Think Up Some Personas
A persona is an imaginary, but specific, person who might use your software and read your documenation. Spend just a few minutes making up 2–3 personas. Give them names, and jot down notes about them.
Example: “Postdoc Pete works in my field and saw me give a talk about my software that computes model exoplanet spectra. He has observational data and wants to see if my models can reproduce them.”
Why: The design of your documentation (and your whole project) will be stronger if it targets specific kinds of people, not just a vague, generic “user”.
Step 4: Envision Your Tutorial
Plan out a tutorial experience that will show new users how to accomplish something cool using your software. We’re not writing any text yet — just outlining.
Why: Your tutorial is your software’s make-or-break moment, so it should be as good as it can be. Outlining first helps us foresee the weak points and think about how we can address them.
Example: “Hmm, Undergrad Ursula is going to need to download a three-gigabyte data file in order to follow my tutorial. I need to figure out where to host it and tell her to kick off the download first so it can run in the background while she installs the code.”
Part 2: “Easy” Drafts
Next, we’ll focus on drafting some of the “easy stuff“. These are bits of documentation that your software really ought to have, but tend to be short and self-contained. When things go well, some of these might take only a few minutes to write.
Step 5: Draft Install Instructions
Draft your installation instructions in a new section of your notes document.
Example: “PlasmaPy may be installed from the
command line using pip: pip install plasmapy”
Why: Your instructions should be extremely short — the modern computing world has tons of tools that make it easy to install all kinds of software. Complicated install instructions are a sign that you’ve got engineering work to do.
In-Depth Guide: Installation Instructions.
Step 6: Draft Citation Instructions
Draft your citation instructions in a new section of your notes document.
Example: “Libcint: An efficient general integral library for Gaussian basis functions, Q. Sun, J. Comp. Chem. 36, 1664 (2015)”
Why: Unfortunately, many users of scientific software need to be reminded to cite it appropriately. Software citation practices also vary widely between fields, so even those who know to cite your software will need to be told how to do so. Everybody wins if you provide easy, prominent, and firm guidance.
In-Depth Guide: Software Citation.
Step 7: Draft Licensing Statement
Draft a licensing statement in a new section of your notes document.
Example: “This project is licensed under the MIT License.”
Why: Formally, people aren’t even allowed to download your software if you don’t provide certain basic information about its legal status. Don’t panic, though — in most cases, you just need to provide a few boilerplate sentences. But you should understand what they mean.
Step 8: Draft Acknowledgments
Draft acknowledgments in a new section of your notes document.
Example: “The MolSSI is supported by the U.S. National Science Foundation through grant number CHE-2136142.”
Why: If a funder supported work on a software project, they almost surely should be acknowledged somewhere in your documentation. Take a few minutes to make sure that all funding sources are listed properly.
Step 9: Draft Contribution Instructions
Draft contribution instructions in a new section of your notes document.
Example: “The Astropy project is made both by and for its users, so we accept contributions of many kinds …”
Why: You should help other people understand if and how they can contribute to your software. New projects may not need more than an encouraging sentence or two. Popular projects might offer a more substantial Contribution Guide.
In-Depth Guide: Contribution Statements.
Part 3: Scaffolding
It’s time to start turning your documentation from plans into reality — which means committing to some specifics.
Step 10: Scope Out Remaining Material
Make a list of other materials that are required for your “minimum viable product” documentation. Most new software probably only needs one more element: some reference material supporting more-experienced users, like API documentation. Use your personas and the Diátaxis model to guide your thinking.
Example: “Beyond a Python API reference, Developer Danielle is really going to want to see a schema for the JSON file that my analysis tool emits.”
Why: You probably have a lot of other things to do besides write documentation. Set a scope now and focus on just getting something out into the world — if it’s a success, you can always write more later.
Step 11: Figure Out Authoring Tools
Select the tool(s) you’ll use to author your project’s documentation and integrate them into your project’s codebase. This may be quick if you’ve done this before, time-consuming if not.
Example: your entire documentation might fit comfortably in a single README.md file.
Example: Sphinx.
Step 12: Stub Out Your Documents
Copy your “easy” draft texts into their intended places in your repository, and make minimal placeholders for the remaining documents that you’ve planned (“Tutorial goes here”).
Look over the skeleton of your site.
Why: Now is a good time to experiment with the organization and style of your site. Is anything essential missing?
Step 13: Figure Out Publishing Tools
Select the tool(s) you’ll use to publish your project’s documentation and integrate them into your project’s codebase. Once again, this may be a time-consuming step if you haven’t set up this kind of workflow before.
Validate the workflow by publishing your skeleton docs.
Example: Continuous deployment to readthedocs.org.
Part 4: Time to Write
The pieces are all in place!
Step 14: Draft The Tutorial
Write a first draft of your tutorial.
Step 15: Draft The Rest
Write up your API reference materials and any other documents that are still placeholders.
Step 16: Review and Revise
You knew this step was coming: take some time to review what you’ve written and revise anything that’s unclear or inaccurate.
Why: TKTK
Step 17: Publish!
TKTK.