Chapter 8: Tools and Workflow

The right tools won’t write your book for you, but the wrong tools will slow you down, introduce friction, and create problems you don’t need. This chapter covers the toolchain and workflow that support a smooth writing process for technical books.

Choosing a Writing Format

The format you write in determines what tools you can use, how easily you can collaborate, and what publishing options are available.

Markdown

Best for: Self-published books, developer-oriented content, open-source books.

Pros:

• Plain text, version-controllable with Git.
• Widely supported. Renders in GitHub, VS Code, and hundreds of other tools.
• Easy to learn, fast to write.
• Converts to HTML, PDF, EPUB via tools like Pandoc.

Cons:

• Limited formatting options without extensions.
• No native support for complex layouts, sidebars, or callout boxes (though many tools add these).
• Tables are awkward to write and maintain.

AsciiDoc

Best for: Books published through O’Reilly (their publishing platform supports AsciiDoc natively) or those needing richer formatting than Markdown.

Pros:

• Richer formatting: callout boxes, admonitions, cross-references, includes.
• Still plain text and version-controllable.
• Excellent for long-form technical writing.

Cons:

• Steeper learning curve than Markdown.
• Smaller ecosystem of tools and renderers.

LaTeX

Best for: Academic and mathematical content. Books heavy on equations and formal notation.

Pros:

• Unmatched typographic quality, especially for math.
• Precise control over layout.

Cons:

• Steep learning curve.
• Verbose syntax that clutters the writing experience.
• Difficult for collaborators who don’t know LaTeX.

Word Processors (Google Docs, Word)

Best for: Collaboration with non-technical editors. Working with traditional publishers who expect Word manuscripts.

Pros:

• Familiar to everyone.
• Built-in commenting and suggestion features.
• Track changes for editing workflows.

Cons:

• Not version-controllable in a meaningful way.
• Code formatting is painful.
• Merging changes from multiple reviewers is tedious.
• Large documents become sluggish.

Recommendation

For most technical books aimed at a developer audience, Markdown or AsciiDoc with Git version control is the best choice. You get the benefits of plain text (diffable, mergeable, portable) with enough formatting power for technical content.

The Writing Environment

Text Editor or IDE

Use whatever you are comfortable writing prose in. Popular choices:

• VS Code: Excellent Markdown preview, extensions for word count, spell checking, and formatting.
• Typora / Obsidian / iA Writer: Distraction-free Markdown editors with live preview.
• Vim/Neovim: For those who prefer to stay in the terminal. Plugins like goyo.vim provide distraction-free writing.
• Emacs Org Mode: A powerful option for those already in the Emacs ecosystem.

The key feature you need: live preview of formatted output so you can see what your reader will see.

Spell Checking and Grammar

• Built-in spell check: Most editors have this. Enable it.
• LanguageTool: Open-source grammar checker. Available as a VS Code extension and standalone tool.
• Vale: A prose linter that checks for style and consistency. Configurable with custom rules.

Distraction Management

Writing requires sustained focus. Consider:

• A full-screen or “zen mode” in your editor.
• Website blockers during writing sessions.
• A dedicated writing environment (a separate user profile, a different desk, even a different computer).

Version Control

Use Git

Track your manuscript in Git. Full stop. This gives you:

• History: Every change is recorded. You can always go back.
• Branching: Experiment with restructuring without risking your main manuscript.
• Backup: Push to a remote repository (GitHub, GitLab) for automatic off-site backup.
• Collaboration: Reviewers can submit feedback as pull requests.

Repository Structure

A clean structure for a book repository:

my-technical-book/
  chapters/
    01-introduction.md
    02-getting-started.md
    ...
  code/
    chapter-01/
    chapter-02/
    ...
  images/
    chapter-01/
    chapter-02/
    ...
  appendices/
    a-setup-guide.md
    b-reference.md
  book.yaml          # Metadata (title, author, description)
  bibliography.md    # Sources and references
  glossary.md        # Terms and definitions
  Makefile            # Build commands
  README.md

Commit Practices

• Commit at the end of every writing session.
• Use meaningful commit messages: “Complete first draft of Chapter 5” is better than “updates.”
• Tag milestones: first-draft, tech-review-complete, final.

Building and Previewing

Pandoc

Pandoc is the Swiss Army knife for document conversion. It converts Markdown to PDF, EPUB, HTML, DOCX, and more.

Basic usage:

pandoc chapter-01.md -o chapter-01.pdf

For a full book with metadata and styling:

pandoc --metadata-file=book.yaml \
       --toc \
       --number-sections \
       chapters/*.md \
       -o book.pdf

mdBook

If you are writing for a web audience, mdBook generates a clean, navigable website from Markdown files. Ideal for open-source books hosted on GitHub Pages.

Honkit / GitBook

Similar to mdBook but with more features. Produces both web and PDF/EPUB output.

Custom Build Scripts

As your build process gets more complex (preprocessing code examples, generating diagrams, running tests), wrap it in a Makefile or build script:

build-pdf:
    pandoc --metadata-file=book.yaml chapters/*.md -o output/book.pdf

build-epub:
    pandoc --metadata-file=book.yaml chapters/*.md -o output/book.epub

test-code:
    cd code && pytest

all: test-code build-pdf build-epub

Managing Code Examples

Keep Code and Prose Separate

Store code examples in their own directory, not embedded only in the manuscript. This lets you:

• Run and test code independently.
• Include code in the manuscript via file references (supported by AsciiDoc and some Markdown tools).
• Keep code examples in sync across chapters.

Automated Testing

Set up CI (GitHub Actions, GitLab CI) to:

1. Run all code examples.
2. Run linters on code.
3. Build the manuscript to catch formatting errors.

This catches broken examples early, before they reach readers.

Code Inclusion

Some tools let you include external code files in your manuscript:

AsciiDoc:

[source,python]
----
include::code/chapter-01/example.py[]
----

This means you only maintain one copy of each example, and it’s the one that gets tested.

Backup Strategy

Your manuscript is months of work. Protect it.

• Git remote: Push to GitHub/GitLab after every writing session.
• Local backup: Time Machine, rsync, or equivalent.
• Cloud sync: Dropbox, Google Drive, or similar for an additional copy.
• Export regularly: Generate PDF/EPUB snapshots at milestones.

Losing a manuscript to a hard drive failure is a preventable disaster.

Collaboration Workflow

Working With Co-Authors

If you have a co-author:

• Use Git branches. Each author works on separate chapters.
• Establish style guidelines early (see Chapter 6 formatting conventions).
• Meet regularly to review each other’s chapters and ensure consistency.
• Use pull requests for cross-chapter changes.

Working With Editors

If your editor doesn’t use Git:

• Export chapters to Google Docs or Word for their review.
• Use their tracked changes/comments.
• Apply their feedback back to your Markdown/AsciiDoc source.
• This is tedious but workable.

If your editor can use Git:

• They review via pull requests.
• Comments become GitHub issues.
• This is far more efficient.

Key Takeaways

• Choose a plain-text format (Markdown or AsciiDoc) for version control and flexibility.
• Use Git for your manuscript. Commit regularly, tag milestones.
• Set up Pandoc or a similar tool for building PDF, EPUB, and HTML output.
• Keep code examples in a separate, testable directory.
• Automate code testing with CI to catch broken examples early.
• Maintain multiple backups — your manuscript is irreplaceable.
• Establish collaboration workflows early if working with co-authors or editors.

>> You can subscribe to my mailing list here for a monthly update. <<