My go-to documentation environment
I’m a documenter; I document nearly everything I do. That’s probably also the reason I like writing this blog. However, writing documentation is nothing without good, or at least decent tooling. I’ve tried many things, and at last this solution has turned out to be my go-to. It has been perfect three times in a row now, including at an organization that had little to no actual or centralized documentation. So what is this go-to tool?
Well, it’s not really a tool; it’s a hosted application, which can be called an tool, and I prefer to host on an internal network. Documentation can include sensitive information about system design and setup. Some might not realize that documentation can be a point of reference or even an entry point for malicious actors.
BookStack
BookStack is amazing, and it's my go-to self hosted OSS app. I mean i can tell you about the functions, but i can't tell it better then them:
Features
Free & Open Source
BookStack is fully free and open, MIT licensed. The source is available on GitHub. There is no cost to downloading and installing your own instance of BookStack.
Easy, Simple Interface
Simplicity has been the top priority when building BookStack. The page editor has a simple WYSIWYG interface and all content is broken into three simple real world groups:
Searchable and Connected
The content in BookStack is fully searchable. You are able to search at book level or across all books, chapters & pages. The ability to link directly to any paragraph allows you to keep your documentation connected.
Configurable
Configuration options allow you to set-up BookStack to suit your use case. You can change the name, logo and registration options. You can also change whether the whole system is publicly viewable or not.
Simple Requirements
BookStack is built using PHP, on top of the Laravel framework and it uses MySQL to store data. Performance has been kept in mind and BookStack can run happily on a $5 Digital Ocean VPS.
Built-In diagrams.net
The page editor within BookStack has diagrams.net drawing capability built-in, allowing the quick and easy creation of diagrams within your documentation.
Multi-Lingual
BookStack users can set their preferred language. Thanks to great community contributors, current languages built into BookStack include EN, FR, DE, ES, IT, JA, NL, PL, RU and many more.
Optional Markdown Editor
If you prefer to write in Markdown then BookStack supports you. A markdown editor is provided and includes a live-preview as you write your documentation.
Integrated Authentication
As well as the default email/password login social providers such as GitHub, Google, Slack, AzureAD and more can be used. Okta, SAML2 and LDAP options are available for enterprise environments.
Powerful Features
On top of the powerful search and linking there is also cross-book sorting, page revisions and image management. A full role and permission system allow you to lock down content and actions as required.
Multi-Factor Authentication
MFA is built in & can be enforced at a per-role level where desired. MFA options include TOTP (Google/Microsoft Authenticator, Authy, etc...) and static backup codes.
Dark & Light Modes
BookStack provides its user interface in both a light theme and a dark theme, saving the eyes of those that prefer to work in the shadows. This is configurable at a user level.
Copied from source: https://www.bookstackapp.com/
How do i set it up?
Bookstack works with Shelves, Books, Pages and Chapters.
Shelves
I set these up as the containers of the environments, let's say you are documenting an Azure resource setup. Or something else in Microsoft's Cloud ecosystem. Then i'll call the shelve Azure Documentation:
In azure we have an resource called NGINXaaS, So i create a book for this
And then for every configuration within NGINXaaS a page. it doesn't have to be as detailed as i do. But i like to give my collegaues as much information as possible.
If you make good use of the tags searching becomes very powerfull. Let's say one of my collegueas gets an call about a service on xx.xx not working. He can just fill in the domain in the searchbar and get the corrosponding documentation:
Why it's perfect to me (showcases)
I can quickly draw complex connections in minutes within my documentation:
The export function is great to share a manual with an external user, when page permissions can't be used.
Revision support, watching, commenting, attachments etc etc.
Nice markdown to make it look amazing:
Code blocks with syntax highlighting:
I think you'll understand why it has become my go-to if possible ;)
(if my blog was full of documentation i would've ran it from BookStack too, and if you use it for your organisation make sure to donate!)
Proost,