Don’t be casual about documentation
Or you might miss out on many users for your software.
So, you came up with a really nice implementation that solves a specific problem. You’ve just published your well-tested code to GitHub. And that’s it, right? Well, if you want users to actually make use of your code, you need good documentation. You might know all the quirks of your software, you might know how to call your API (hopefully), you know what config options there are available and what range this one parameter has. But don’t expect other, potential first-time users of your code to read your thoughts.
Document your software.
If you want to convert me from a potential user to a real, enthusiastic user, you will have to do more than just dump whatever crosses your mind into a Readme file. Here are some personal thoughts on what a good Readme should be made up of.
Language
English as language. All languages are beautiful but unfortunately I can only speak a few. English is an international language and well-established in the scientific community. English is also the de-facto Lingua franca when it comes to coding, so stick to it and use it in your projects: for your documentation, but also for naming variables/functions/etc. and for writing doc strings. This will allow others to better comprehend your code.
Know your English. I don’t expect poetry when reading your documentation, but please have your English grammar and orthography together. Write full sentences that end in a period. Moreover, place a comma when starting sentences with an adverbial clause. Having pointed this out, you might also want to use the perfect participle, e.g. “Having set this environment variable, the program will log everything…”. Make use of a spell checker in your browser (you can usually set up multiple languages that the browser should check for) or IDE (e.g. use the awesome Code Spell Checker for VSCode).
Sections
Subdivide your Readme/documentation into multiple pieces. This might make sense even for very small projects. For example, I’d like to know the motivation behind the program and what use cases it tries to solve. This will allow me to quickly figure out if your package is something for me or not. In Markdown, make use of the special syntax for sections:### Motivation.
If I reckon your program as good fit, I’d like to quickly see how it’s used in action. For that, a Quickstart or Overview (etc.) might be useful, followed by an Installation section and an API reference with detailed explanations of what I can pass to your program. I’d also like to see the default values of your params in a list/table. A Configuration section would be nice too. Maybe even add an FAQ. Organizing your content in sections also allows people reliant on screen readers to quickly find what they are looking for.
Readme vs. dedicated webpage
Start to write your documentation in a Readme. But sometimes your project is too big and the Readme is getting very long. You might still be able to keep it well-structured, like Just does. It’s advantageous in the sense that I can search (Ctrl + F) the whole documentation and quickly find what I’m looking for. But it’s not the easiest to navigate (even with a table of contents). And other solutions might have a good search built-in (though that’s not too often the case in my past experience).
If you feel your Readme is getting out of hand, a dedicated documentation website might be the better fit. And it’s not that hard to setup with GitHub Pages (for free). I can recommend Just the Docs as responsive Jekyll theme. Material for MkDocs offers another great documentation framework. And Sphinx is a powerful tool for Python documentation. In these cases, I still suggest to keep a very short Readme where you can briefly introduce the project and then link to your documentation.
Another free option is to use a GitHub Wiki like the great LaTeX workshop extension for VSCode does. Additionally, they provide a table of contents in their Readme that links to specific wiki pages. Their documentation is thorough and really well-structured in my opinion. Try out various tools and find the one you get along with best.
Formatting
When it comes to readability, formatting choices play a crucial role. Leverage your tools at hand. For example, if you write Markdown on GitHub, check out their quickstart guide. You might also like alerts/highlight boxes and collapsed sections (those can help you out especially in long documents). Surround any code-related content with backticks (`) in order to get a gray box around it: int x = 5; or create_table(). This allows to quickly distinguish prose from code. For longer statements (or whenever you want to put code on a separate line), use three backticks. Don’t forget to put a language specifier (e.g. js, py, rubyetc.) to get some nice syntax highlighting.
And there’s a lot more formatting options out there. Use the tools at your disposal to let your documentation shine.
function informMediumReaders() {
alert("Use three backticks (```) to start a code block in Markdown");
}Put yourself into the 3rd perspective
This is probably the hardest part. You’re deep into your application and know exactly what’s is all about. Try to explain what it does to other people adept in different domains, e.g. to your family that might not know anything about programming, but also to friends who have acquired programming experience (but maybe in different areas). You will soon find that even the vocabulary can be a barrier. This is part of the art of didactics that teachers and profs have to face. You know they’re not very good at it if you think groups, rings and vector spaces (math concepts) are introduced in elementary school.
Of course, you might tailor your application to a very specific, niche set of customers/users. But this just determines where you set the threshold. Even for experienced users, there might be vocabulary that you have to clarify or want to call to mind. I think it’s better to establish a broad common ground than no common ground at all risking that users turn away frustrated.
And it’s not just about unknown vocabulary. It’s about what you consider to be most important and where you abridge. There will always be a point where you have to “cut off” and assume familiarity of your reader with the topic. When you showcase the syntax of your new programming language, you probably don’t want to explain what a transistor is and how the Z1 mechanical computer adds up two numbers. When you write a library for scientific plotting, you can probably skip explaining what LaTeX is about. When you’re designing a tool that creates interactive visualizations of how the Rust programming language thinks about a given program (aquascope), you will probably not have to explain what Rust is in the first place.
But if in doubt, it’s always nice to provide links for your audience if they want to dive deeper. These might be links to sections you’ve written (e.g. in another markdown file or HTML page that is not as prominently featured as other more important pages in the navbar), or to external websites that you found useful when discovering the domain at hand for the very first time on your own.
The hard part here is to find a balanced middle ground: being broad enough to include many users and welcome newcomers, but specific enough to come to a point and to explain what your program is about in a specific, possibly very narrow domain. In order to find this middle ground, you need to (at least once) forget all the code you’ve written in the project and put on the hat of your target audience. Put yourself in the shoes of a user who learns about your project for the first time. They haven’t seen any line of your code and now browse through your Readme/documentation.
In my opinion, this is why empathy is a crucial factor in successful communication. And that’s what documentation is all about: communicating with your users what your code is about and selling a coherent experience for them along the whole lifecycle: from your visual presentation (brand, logo, vision), to the quickstart guide, detailed API reference, to how stable your API is, how usable it is (does it provide a help flag that prints the most useful commands?), to how well errors provide information of what went wrong. Every contact point of your software with the user will shape their impression with your product. Documentation is one ingredient for it; and a very important one. Without it, your project is probably useless for many.
Marketing
Not my favorite topic. Marketing is tedious (at least for me) and most of the time resides on the other side of the spectrum of what you do as a programmer. But you shouldn’t underestimate the power that comes with it. And it doesn’t have to be too sophisticated:
- You don’t need a logo, but a visual component in your documentation is always nice to look at and helps in crafting a “brand” that users might remember more easily than just your project name (choose that one wisely too). Get creative: your logo can be hand-drawn on paper, or on a computer, you can also check out free iconography online or even use AI to assist you with this task.
- Apart from a logo, you may want to draft a so-called social preview. In the settings of a a public GitHub repo, you can upload an image that will be shown as preview whenever you share the link to your repo on social media. This image is also featured on GitHub’s explore page; and I bet that more users click on repositories that have such an image than those which don’t include one. I’ve also designed one for my raspi-captive-portal project.
- Marketing is more than “just” the visual appearance. It’s also about how you acquire new users, e.g. by increasing your outreach. For example, you could write blog posts on another platform showcasing your app in various scenarios. Or maybe you present your project at a local conference and get to know some interesting people alongside. Or you start a video series / dev blog like aarthificial (Jacob) did for game development and in order to present his mind-blowing library motion canvas he developed.
- It’s also how you deal with your “customers”, e.g. how long do you take to respond to GitHub issues and in what quality? How welcoming are you to new contributors (if you want to allow them, that’s your choice). Have you set up a contribution guide with guidelines on how to get started as new contributor and what style conventions to follow in your project? You might also want to check out the great page “Starting an open source project”. If you’re not actively developing/maintaining a project anymore, it’s courtesy to archive the repository or to create a warning box at the top of your Readme indicating the status of it. This way, you avoid frustrated users who find out that your project is on ice as soon as they have already got acquainted with it.
Learn from others & ask for help
There’s a chance you already had a frustrating experience with someone else’s code and/or documentation. Learn from it and recall these bad experiences when you write your own documentation. Do likewise for stellar examples. How you do it can be manifold:
- You notice a nice Markdown element in another Readme? For example, a beloved project has a centered heading and a centered logo at the top? Just click on “edit” to see the Readme in its raw form and find out how they achieved this. Or you like how a project organized their arguments for an API in a neat table? Then try this out for your own project as well and see if it’s suitable. You like the clean design and font of a blog? Keep its design choices and structure in mind when you write your own.
- It could also be more general, e.g. you like the overall structure of a project and how they guide users through it. Or how they have specific pages for newcomers and more experienced users. Or you appreciate that they provide their documentation not just as webpage, but also as a PDF file for you to download. Or that they have interactive playgrounds.
Find what you value most in other projects and use that as reference for your own endeavors.
Last but not least, ask people in your surroundings to review your project, e.g. to proof-read parts of your documentation (let them make sure that all of your links are working!) or to alpha-test your software. Only send them a link to your documentation to start with; everything else should be self-explanatory, e.g. how they can install it on their Windows/Linux/macOS/whatever machine and how they use it and gain value from the code you’ve written.
Because in the end, that’s what you want, right? Spare other people the pain you went through and make their lives a bit easier. Don’t forget to add an (MIT) license such that the world can actually make use of your code without being sued.
