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.
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:
- Run all code examples.
- Run linters on code.
- 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.