A Look at Some Interesting Documentation Methods

Dan Brown posted on the 25th of August 2022

As the maintainer of a documentation platform, I find myself taking note of methods of how people go about creating documentation. I strongly believe that there’s no “single best method” when it comes to documentation, and that any option that’d actually be used is a value gain.

In this post I’d like to step out the specific context of BookStack and take a look at some less common forms of documentation that have piqued my interest.

Jeff Geerling’s GitHub Issues

Jeff Geerling, commonly known for his Raspberry Pi and Ansible expertise, is what I’d consider a master community documenter on many fronts. He’s published books, produces videos and maintains a blog; All rich with valuable documentation content.

An additional method that Jeff uses, which I want to specifically look at here, is documenting through GitHub issues. As Jeff works on a project he’ll often open an equivalent GitHub project, then open issues for specific problems he comes across, then update that issue with information as he progresses. Here’s an example of such an issue. This essentially provides a timeline of how particular tasks are worked through, while also providing an open location for community input & feedback.

Many projects use something like GitHub issues, of which can build as a repository of documentation over time, but the difference here is that it’s the project author themselves going the extra mile to write clear detail for others to consume. Jeff will often reference one of his issue pages within his videos, and I notice a keen sense of pride when he does this which I love to see.

Wendell’s Forum Posts

Wendell is well known in the YouTube tech space for his Computer Tech and Linux knowledge primarily relayed through the Level1Techs and Level1Linux YouTube channels. While watching his videos, I’ve been intrigued by his referencing of forum posts.

The Level One team maintains an active forum for their community. When working on a solution, Wendell will often document the process within a forum post, as can be seen in this example. Much like Jeff’s GitHub issues, this provides opportunity for community interaction and involvement which can add further value in itself to future readers. Comparatively, I think posting within a forum in this manner has a double benefit of adding value direct into the community, helping growth, while putting the content directly into the view of an actively engaged targeted audience.

My Learnings From Producing Video Guides

The value of video for documentation is well established, with both of my previous examples featuring great examples of video-based documenters. It’s only since I’ve been making videos myself for BookStack that I’ve come to understand their value from an author’s perspective. The ability to send someone a timestamped video link, showing the steps or process they need to follow, has been extremely handy for me, especially for more complicated subjects.

I believe a lot of the value I’ve found in video has been in its ability to visually provide a lot of context very quickly, which you’d have to otherwise establish in writing, either within documentation or alongside providing a link to the documentation upon a specific request.

Being able to look back on a full end-to-end process, with every detail included, provides the entire picture compared to which is essentially a second-hand abstraction with written content. For example, If a user interface has changed since the documentation has been made, that’s instantly visible within a video whereas, unless that has been specifically screen-shotted or verbosely described, such a scenario can add a significant point of confusion in written content.

Header Image Credits: Photo by Rafael Leão on Unsplash