As the US gears up for a second Trump administration, scientists and archivists are concerned about digital preservation of resources, webpages and data. This is justified; not only is the internet rotting, last Trump term many resources about climate change were quietly scrubbed from the Environmental Protection Agency (EPA) website. In general we need to put more resources towards digital preservation, so I welcome this.

As scientists upload code, results and methodologies to be shared more widely, I have one request:

Don’t forget about documentation!

Documentation is the thing that helps other people to run your code and reproduce (or not) your results. Without it, most of us will just stare at your repositories cluelessly, shrug, and go back to watching cat videos.

Here are some assorted thoughts on what makes for good documentation:

Write down everything. No, more than that

The key to writing documentation that other people can read is to write down as much as possible. Yes, even the things you might think are obvious. Don’t take it for granted that the reader shares the same knowledge base as you.

Make everything explicit

Related to writing down everything – don’t leave anything implicit. Write every single step out explicitly. If you don’t do this, people will miss the implied steps and not be able to make your code work the way you wanted it to.

Make it simple

Academics are known for our convoluted writing, for jargon, and for silly acronyms.

None of that has a place in documentation. (OK, maybe the silly acronyms.)

Assume whoever is reading needs to read the simplest version possible. That means splitting up your sentences, writing clearly, and avoiding the passive voice if you can.

Diagrams are cool and good

Nobody wants to read a wall of text. People want screenshots, cool graphs, and GIFs. Break up paragraphs with images.

Get extra eyes

In every big writing project, there comes a time when you start getting sick of looking at your own text. Documentation is no different.

Ask someone – preferably someone who knows about writing but isn’t a subject matter expert – to review your documentation. Pay attention to anything they tell you is especially unclear. Work on making that clearer. Repeat.

Documentation is never going to be perfect, but well-written documentation goes a long way towards promoting reproducibility.