What is good documentation, how does it look like and where can I find it? There’s always that moment in the life of an engineer when you sit in front of your laptop with your warm cup of coffee/tea and a blank page opened, trying to come up with a beginning of that documentation page for your team.

Beginnings are always harsh, unfortunately you can only overcome them by just writing something, even a bare brain-dump. Keep in mind, when you start writing a docu, the initial version is always a Draft.

We’ve all skimmed through RFCs and have noticed some of them are in Status: Draft; why, because they have to be peer-reviewed. You’ve marked a document Standard when everyone reviewed and proofed it of grammar and typos.

Here are some good examples of actionable documentation.

Discord releases #

Version releases are also documentation. Discord writes them in a fun way, so imho I call this fun documentation.

If you click on the I gotchu link, you’ll end up on another fun docu page with pictures and explanations of what’s new! Now this is the kind of page that never tires a reader. Sure, an image is a thousand words, but there are also gifs with interactive actions being explained, take a look

You can clearly distinguish from this picture a simple guideline with bullet point steps with detailed actions required from the User. Not only that, an information bubble (green background) emphasizes key elements to the reader, something like FYI.

Memgraph documentation #

Memgraph have done a good job here laying down the driver connectivity via the aforementioned programming languages, all clearly distinguished in their own boxes.

Closing notes #

What’s common on both documentation pages (Memgraph and Discord) is at the footer they have a way of collecting user feedback. It’s a simple question that doesn’t require any account, just a humble yes or no. You can also see how many people found it useful.