How To Write A Technical Book (One Man's Modest Suggestions)

Writing Tools Writeup.markdown

Digital Toolchain for Book Authors

Text markup and structure

• So many light markup formats to consider
  • Markdown
  • Textile
  • reStructuredText
  • Asciidoc
  • Most compile to HTML, PDF, DocBook
• Get handy with PanDoc (but man, the haskell bootstrapping is a pain)
• List of formats:
  • Wikipedia Markup Formats
  • Prefer AsciiDoc due to its ability to output DocBook
  • Markdown is nicely rendered by GitHub and other desktop tools, but really isn't a full book authoring format.
• We used OrgMode for outlines and planning
• We used Dropbox for syncing it all
• We used Markdown for any quick write-ups and to-be-integrated raw pieces stored in a separate directory
  • QuickLook plugins for Markdown on MacOSX exist. Very nice.
  • Markdown editors now exist for the iPad, iPhone and Desktop
  • Mou (Desktop)
  • Markdown Mode (Emacs)
  • Elements (iPad, iPhone)

Format, Authoring Tools

• Scribe
  • This is a wrapper over AsciiDoc to easily produce PDF, HTML, DocBook
  • Scribe Template
  • Scribe Engine
  • Guard for Scribe
  • Has a few bugs that will be getting love in the next few months
• Your Own Toolchain
  • Rake script for Presentation Patterns
• Will try to OSS some of this stuff in the Spring and I'll be hacking on Scribe as I give more time to GitHub employment
• XML
  • For pure XML (DocBook) authoring, I liked:
    • Oxygen
    • XMLMind
    • Emacs nXML mode
  • Some of these have DocBook stylesheets built in or a live editor
• The drawback to AsciiDoc is the lack of not having the full DocBook tag vocabulary
  • You can always convert towards the end of the book and use DocBook from there on out, but that seems like a nasty mode shift.

Inline Code Samples

• Q: Code insertion (such that it can be tested)
• AsciiDoc uses pygments to style the most common languages
  • Pygments Homepage. Also used internally at GitHub
  • More or less built-in to Asciidoc toolchain
• Nest the examples as a Git submodule within the Git scribe book or other book technology. You can OSS the examples early. We did with Gradle.

Example code in Asciidoc (standalone files)

[[EX-MAVEN-001]]
.The smallest possible Maven pom.xml
====
[xml]
source~~~~
include::example_code/maven-smallest-maven-pom/pom.xml[]
source~~~~
====

Audited version history

• Q: Naturally, we both prefer Git
• Git, without a doubt, but with more than just a master branch
  • Squash branch commits for bigger "units of work", not noisy commits which some of my co-authors seem to like to create
• CIed book build
• Used just shell scripts and cron
• Or trigger on Mac folder changes with Hazel

Inline comments and threads/discussions

• Q: GitHub comments?
• Remarks DocBook tags in the DocBook files (Presentation Patterns)
  • http://www.docbook.org/tdg/en/html/remark.html
  • I wrote and had my brother, a JS and HTML guy, write an awesome stylesheet that made the remarks pop in Red.
  • Remark tags generate "notes" in PDFs. Awesome.
  • TODO keyword in the text with a build script that found and listed them all (like an ack)

Outlining strategy/hacks

• Q: How did you avoid 10 rewrites?
• A: Let it bake for 2 years in outlines and 1 year in a draft. INSANE. But nice.

So, how can this be done in a more reasonable way?

1. Level one bullets only. Revise. Review.
2. Write 5% of the book based on passion.
3. Level two bullets. See impact on level 1. Revise. Review.
4. Consider the outline locked unless there is something massively broken.
5. Write a crappy first draft with high velocity.
6. Stick to the outline. If you need to change it, change it, but don't let the prose drive the plan.

Writing Hacks

1. Use Dragon Dictate and a Plantronics wireless boom mic. Thank me later. I cranked out 5200 words in a day with it. And you can listen to music while you dictate.
2. Write every day. Even if just a little bit. I am the worst offender of this advice, but I am trying to stick to it.

Task tracking

• Q: We've been evaluating trello.com
  • Demo video
• OrgMode
  • Emacs major mode
    • http://orgmode.org/
  • Filter by person assigned
    • http://orgmode.org/guide/index.html
  • Used for almost everything in the PPAP planning and assignment process

Sample of OrgMode (Raw)

* Admin: Deadlines:
** Initial Marketing <2011-12-19 Mon>
**** DONE Snappy back-cover text <2011-12-19 Mon>                  :nf:mm:ns:
**** DONE final(-ish) TOC<2011-12-19 Mon>                          :nf:mm:ns:
** First Draft                                                     :nf:mm:ns:
This is the draft that goes to Eileen & our technical review, not to
be confused with Pearson's process
** Final Draft <2012-02-15 Wed>                                    :nf:mm:ns:

Contract management

Publishers are in the dark ages with this sending shredded trees all over the place asking you to physically sign 6 copies of a signature sheet. WTF!? Ideally this idea would integrate with electronic document handling like GH uses for its new employees.

via Phil Haack

Integrated Reporting

Royalty and sales reporting typically sucks. Outdated sites that make Geocities look like the next GH. This site could provide a nice reporting dashboard for authors to look at.

Basically, this could be the one stop shop for publishers and authors to collaborate on a book.

via Phil Haack

---

Hope that helps.

Matthew McCullough
matthewm@ambientideas.com
http://ambientideas.com/blog
matthew@github.com
http://github.com/training
@matthewmccull