The Problem with Documentation in Teams

Documentation is always a challenge in development teams, especially when faced with changing requirements and tight deadlines. Even when an application stabilizes after release, documentation often gets lower priority compared to backlog features. Yet, asynchronous documentation is an absolute necessity for onboarding new team members and supporting existing developers.

Many tools like GitBook, VuePress, or Docusaurus require setup overhead or hosting permissions. mdBook solves these friction points efficiently.

MdBook as the Suggested Tool

GitHub Source: https://github.com/rust-lang/mdBook Demo: https://rust-lang.github.io/mdBook/

I find it to be lightweight, easy to configure, set up and use without all the bells and whistles.

Positives of mdBook

• Easy to learn: Takes less than 10 minutes to understand the core workflow.
• Zero npm dependencies: Generates static raw HTML/JS output.
• Simple hosting: Can be distributed via shared drives (e.g. OneDrive) by opening index.html directly in the browser.
• Customizable styling: Supports additional-css under [output.html] in book.toml.
• Built-in Search: Instant keyboard shortcut search (S).

Downsides or Considerations

• Requires Rust/Cargo installation to install the binary (cargo install mdbook). You can get around the install with docker.
• Limited themes selection. You can create your own and configure it as the default but that takes some tweaking.