• So many light markup formats to consider
  • Markdown
  • Textile
  • 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)

• 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.

• 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.

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

• 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

• 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.
  • TODO keyword in the text with a build script that found and listed them all (like an ack)

• 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.

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.

• 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

* 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:

Hope that helps.

Matthew McCullough
[email protected]
http://ambientideas.com/blog
[email protected]
http://github.com/training
@matthewmccull