Skip to content

Instantly share code, notes, and snippets.

@developerworks

developerworks/Writing Tools Writeup.markdown

Forked from mojavelinux/Writing Tools Writeup.markdown
Created March 12, 2018 16:26
Show Gist options
  • Save developerworks/7d2d77d6b6b1e697bc6025727dfa9aba to your computer and use it in GitHub Desktop.
Save developerworks/7d2d77d6b6b1e697bc6025727dfa9aba to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @mojavelinux mojavelinux revised this gist Jan 30, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -4,7 +4,7 @@
    * So many light markup formats to consider
    * [Markdown](http://daringfireball.net/projects/markdown/)
    * [Textile](http://www.textism.com/tools/textile/)
    * [reStructuredText](http://docutils.sourceforge.net/rst.html)
    * [reStructuredText](http://docutils.sourceforge.net/rst.html)
    * [Asciidoc](http://www.methods.co.nz/asciidoc/)
    * Most compile to HTML, PDF, [DocBook](http://www.docbook.org/)
    * Get handy with [PanDoc](http://johnmacfarlane.net/pandoc/) (but man, the haskell bootstrapping is a pain)
  2. @mojavelinux mojavelinux revised this gist Jan 30, 2012. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -4,6 +4,7 @@
    * So many light markup formats to consider
    * [Markdown](http://daringfireball.net/projects/markdown/)
    * [Textile](http://www.textism.com/tools/textile/)
    * [reStructuredText](http://docutils.sourceforge.net/rst.html)
    * [Asciidoc](http://www.methods.co.nz/asciidoc/)
    * Most compile to HTML, PDF, [DocBook](http://www.docbook.org/)
    * Get handy with [PanDoc](http://johnmacfarlane.net/pandoc/) (but man, the haskell bootstrapping is a pain)
  3. Matthew McCullough revised this gist Jan 29, 2012. 2 changed files with 12 additions and 350 deletions.
    349 changes: 0 additions & 349 deletions Writing Tools Writeup.html
    View file
    Original file line number Diff line number Diff line change
    @@ -1,349 +0,0 @@
    <!doctype html>
    <html>
    <head>
    <meta charset="utf-8">
    <style>
    h1,
    h2,
    h3,
    h4,
    h5,
    h6,
    p,
    blockquote {
    margin: 0;
    padding: 0;
    }
    body {
    font-family: "Helvetica Neue", Helvetica, "Hiragino Sans GB", Arial, sans-serif;
    font-size: 13px;
    line-height: 18px;
    color: #737373;
    margin: 10px 13px 10px 13px;
    }
    a {
    color: #0069d6;
    }
    a:hover {
    color: #0050a3;
    text-decoration: none;
    }
    a img {
    border: none;
    }
    p {
    margin-bottom: 9px;
    }
    h1,
    h2,
    h3,
    h4,
    h5,
    h6 {
    color: #404040;
    line-height: 36px;
    }
    h1 {
    margin-bottom: 18px;
    font-size: 30px;
    }
    h2 {
    font-size: 24px;
    }
    h3 {
    font-size: 18px;
    }
    h4 {
    font-size: 16px;
    }
    h5 {
    font-size: 14px;
    }
    h6 {
    font-size: 13px;
    }
    hr {
    margin: 0 0 19px;
    border: 0;
    border-bottom: 1px solid #ccc;
    }
    blockquote {
    padding: 13px 13px 21px 15px;
    margin-bottom: 18px;
    font-family:georgia,serif;
    font-style: italic;
    }
    blockquote:before {
    content:"\201C";
    font-size:40px;
    margin-left:-10px;
    font-family:georgia,serif;
    color:#eee;
    }
    blockquote p {
    font-size: 14px;
    font-weight: 300;
    line-height: 18px;
    margin-bottom: 0;
    font-style: italic;
    }
    code, pre {
    font-family: Monaco, Andale Mono, Courier New, monospace;
    }
    code {
    background-color: #fee9cc;
    color: rgba(0, 0, 0, 0.75);
    padding: 1px 3px;
    font-size: 12px;
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
    border-radius: 3px;
    }
    pre {
    display: block;
    padding: 14px;
    margin: 0 0 18px;
    line-height: 16px;
    font-size: 11px;
    border: 1px solid #d9d9d9;
    white-space: pre-wrap;
    word-wrap: break-word;
    }
    pre code {
    background-color: #fff;
    color:#737373;
    font-size: 11px;
    padding: 0;
    }
    @media screen and (min-width: 768px) {
    body {
    width: 748px;
    margin:10px auto;
    }
    }
    </style>
    <title>Writing Tools Writeup.html</title>
    </head>
    <body>
    <h1>Digital Toolchain for Book Authors</h1>

    <h2>Text markup and structure</h2>

    <ul>
    <li>So many light markup formats to consider

    <ul>
    <li><a href="http://daringfireball.net/projects/markdown/">Markdown</a></li>
    <li><a href="http://www.textism.com/tools/textile/">Textile</a></li>
    <li><a href="http://www.methods.co.nz/asciidoc/">Asciidoc</a></li>
    <li>Most compile to HTML, PDF, <a href="http://www.docbook.org/">DocBook</a></li>
    </ul>
    </li>
    <li>Get handy with <a href="http://johnmacfarlane.net/pandoc/">PanDoc</a> (but man, the haskell bootstrapping is a pain)</li>
    <li>List of formats:

    <ul>
    <li><a href="http://en.wikipedia.org/wiki/Lightweight_markup_language">Wikipedia Markup Formats</a></li>
    <li>Prefer AsciiDoc due to its ability to output DocBook</li>
    <li>Markdown is nicely rendered by GitHub and other desktop tools, but really isn&rsquo;t a full book authoring format.</li>
    </ul>
    </li>
    <li><a href="http://orgmode.org">We used OrgMode for outlines and planning</a></li>
    <li>We used Dropbox for syncing it all</li>
    <li>We used <a href="http://daringfireball.net/projects/markdown/">Markdown</a> for any quick write-ups and to-be-integrated raw pieces stored in a separate directory

    <ul>
    <li>QuickLook plugins for Markdown on MacOSX exist. Very nice.</li>
    <li>Markdown editors now exist for the iPad, iPhone and Desktop</li>
    <li><a href="http://mouapp.com/">Mou (Desktop)</a></li>
    <li><a href="http://jblevins.org/projects/markdown-mode/">Markdown Mode (Emacs)</a></li>
    <li><a href="http://www.secondgearsoftware.com/elements/">Elements (iPad, iPhone)</a></li>
    </ul>
    </li>
    </ul>


    <h2>Format, Authoring Tools</h2>

    <ul>
    <li>Scribe

    <ul>
    <li>This is a wrapper over AsciiDoc to easily produce PDF, HTML, DocBook</li>
    <li><a href="https://github.com/schacon/git-scribe-template">Scribe Template</a></li>
    <li><a href="https://github.com/schacon/git-scribe">Scribe Engine</a></li>
    <li><a href="https://github.com/jasonm/guard-git-scribe">Guard for Scribe</a></li>
    <li>Has a few bugs that will be getting love in the next few months</li>
    </ul>
    </li>
    <li>Your Own Toolchain

    <ul>
    <li><a href="http://rake.rubyforge.org/">Rake</a> script for <a href="http://presentationpatterns.com">Presentation Patterns</a></li>
    </ul>
    </li>
    <li>Will try to OSS some of this stuff in the Spring and I&rsquo;ll be hacking on Scribe as I give more time to <a href="http://github.com/training">GitHub employment</a></li>
    <li>XML

    <ul>
    <li>For pure XML (DocBook) authoring, I liked:

    <ul>
    <li><a href="http://www.oxygenxml.com/">Oxygen</a></li>
    <li><a href="http://www.xmlmind.com/xmleditor/">XMLMind</a></li>
    <li><a href="http://www.thaiopensource.com/nxml-mode/">Emacs nXML mode</a></li>
    </ul>
    </li>
    <li>Some of these have DocBook stylesheets built in or a live editor</li>
    </ul>
    </li>
    <li>The drawback to AsciiDoc is the lack of not having the full DocBook tag vocabulary

    <ul>
    <li>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.</li>
    </ul>
    </li>
    </ul>


    <h2>Inline Code Samples</h2>

    <ul>
    <li>Q: Code insertion (such that it can be tested)</li>
    <li>AsciiDoc uses pygments to style the most common languages

    <ul>
    <li><a href="http://pygments.org/">Pygments Homepage</a>. Also used internally at GitHub</li>
    <li>More or less built-in to <a href="http://www.methods.co.nz/asciidoc/">Asciidoc</a> toolchain</li>
    </ul>
    </li>
    <li>Nest the examples as a Git submodule within the Git scribe book or other book technology. You can OSS the examples early. <a href="https://github.com/gradleware/oreilly-gradle-book-examples">We did with Gradle</a>.</li>
    </ul>


    <h3>Example code in Asciidoc (standalone files)</h3>

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

    <h2>Audited version history</h2>

    <ul>
    <li>Q: Naturally, we both prefer Git</li>
    <li>Git, without a doubt, but with more than just a master branch

    <ul>
    <li><a href="https://makandracards.com/makandra/527-squash-several-git-commits-into-a-single-commit">Squash branch commits</a> for bigger &ldquo;units of work&rdquo;, not noisy commits which some of my co-authors seem to like to create</li>
    </ul>
    </li>
    <li><a href="http://jenkins-ci.org">CIed</a> book build</li>
    <li>Used just shell scripts and cron</li>
    <li>Or trigger on Mac folder changes with <a href="http://www.noodlesoft.com/hazel.php">Hazel</a></li>
    </ul>


    <h2>Inline comments and threads/discussions</h2>

    <ul>
    <li>Q: GitHub comments?</li>
    <li><a href="http://www.docbook.org/tdg/en/html/remark.html">Remarks DocBook tags</a> in the DocBook files (Presentation Patterns)

    <ul>
    <li>http://www.docbook.org/tdg/en/html/remark.html</li>
    <li>I wrote and had <a href="http://ambientideasphotography.com">my brother, a JS and HTML guy</a>, write an awesome stylesheet that made the remarks pop in Red.</li>
    <li>Remark tags generate &ldquo;notes&rdquo; in PDFs. Awesome.</li>
    <li><code>TODO</code> keyword in the text with a build script that found and listed them all (like an <code>ack</code>)</li>
    </ul>
    </li>
    </ul>


    <h2>Outlining strategy/hacks</h2>

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


    <p>So, how can this be done in a more reasonable way?</p>

    <ol>
    <li>Level one bullets only. Revise. Review.</li>
    <li>Write 5% of the book based on passion.</li>
    <li>Level two bullets. See impact on level 1. Revise. Review.</li>
    <li>Consider the outline locked unless there is something massively broken.</li>
    <li><a href="http://www.mywritingmylife.com/2011/11/on-writing-the-shitty-first-draft.php">Write a crappy first draft</a> with high velocity.</li>
    <li>Stick to the outline. If you need to change it, change it, but don&rsquo;t let the prose drive the plan.</li>
    </ol>


    <h2>Writing Hacks</h2>

    <ol>
    <li>Use <a href="http://www.nuance.com/for-individuals/by-product/dragon-for-mac/dragon-dictate/index.htm">Dragon Dictate</a> and a <a href="http://www.plantronics.com/us/product/audio-995">Plantronics wireless boom mic</a>. Thank me later. I cranked out 5200 words in a day with it. And you can listen to music while you dictate.</li>
    <li><a href="http://forums.pragprog.com/forums/235/topics/9874">Write every day</a>. Even if just a little bit. I am the worst offender of this advice, but I am trying to stick to it.</li>
    </ol>


    <h2>Task tracking</h2>

    <ul>
    <li>Q: We&rsquo;ve been evaluating <a href="http://trello.com">trello.com</a>

    <ul>
    <li><a href="http://www.youtube.com/watch?feature=player_embedded&amp;v=aaDf1RqeLfo">Demo video</a></li>
    </ul>
    </li>
    <li><a href="http://orgmode.org/">OrgMode</a>

    <ul>
    <li>Emacs major mode

    <ul>
    <li>http://orgmode.org/</li>
    </ul>
    </li>
    <li><a href="http://orgmode.org/guide/index.html">Filter</a> by person assigned

    <ul>
    <li>http://orgmode.org/guide/index.html</li>
    </ul>
    </li>
    <li>Used for almost everything in the <a href="http://presentationpatterns.com">PPAP</a> planning and assignment process</li>
    </ul>
    </li>
    </ul>


    <h3>Sample of OrgMode (Raw)</h3>

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

    <h2>Big Thoughts</h2>

    <p>Hope that helps.</p>

    <p>Matthew McCullough<br/>
    <a href="mailto:[email protected]">[email protected]</a><br/>
    <a href="http://ambientideas.com/blog">http://ambientideas.com/blog</a><br/>
    <a href="mailto:[email protected]">[email protected]</a><br/>
    <a href="http://github.com/training">http://github.com/training</a><br/>
    <a href="http://twitter.com/matthewmccull">@matthewmccull</a></p>
    </body>
    </html>
    13 changes: 12 additions & 1 deletion Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -112,8 +112,19 @@ So, how can this be done in a more reasonable way?
    be confused with Pearson's process
    ** Final Draft <2012-02-15 Wed> :nf:mm:ns:

    ## Big Thoughts
    ## 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
  4. Matthew McCullough revised this gist Jan 13, 2012. 1 changed file with 349 additions and 0 deletions.
    349 changes: 349 additions & 0 deletions Writing Tools Writeup.html
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,349 @@
    <!doctype html>
    <html>
    <head>
    <meta charset="utf-8">
    <style>
    h1,
    h2,
    h3,
    h4,
    h5,
    h6,
    p,
    blockquote {
    margin: 0;
    padding: 0;
    }
    body {
    font-family: "Helvetica Neue", Helvetica, "Hiragino Sans GB", Arial, sans-serif;
    font-size: 13px;
    line-height: 18px;
    color: #737373;
    margin: 10px 13px 10px 13px;
    }
    a {
    color: #0069d6;
    }
    a:hover {
    color: #0050a3;
    text-decoration: none;
    }
    a img {
    border: none;
    }
    p {
    margin-bottom: 9px;
    }
    h1,
    h2,
    h3,
    h4,
    h5,
    h6 {
    color: #404040;
    line-height: 36px;
    }
    h1 {
    margin-bottom: 18px;
    font-size: 30px;
    }
    h2 {
    font-size: 24px;
    }
    h3 {
    font-size: 18px;
    }
    h4 {
    font-size: 16px;
    }
    h5 {
    font-size: 14px;
    }
    h6 {
    font-size: 13px;
    }
    hr {
    margin: 0 0 19px;
    border: 0;
    border-bottom: 1px solid #ccc;
    }
    blockquote {
    padding: 13px 13px 21px 15px;
    margin-bottom: 18px;
    font-family:georgia,serif;
    font-style: italic;
    }
    blockquote:before {
    content:"\201C";
    font-size:40px;
    margin-left:-10px;
    font-family:georgia,serif;
    color:#eee;
    }
    blockquote p {
    font-size: 14px;
    font-weight: 300;
    line-height: 18px;
    margin-bottom: 0;
    font-style: italic;
    }
    code, pre {
    font-family: Monaco, Andale Mono, Courier New, monospace;
    }
    code {
    background-color: #fee9cc;
    color: rgba(0, 0, 0, 0.75);
    padding: 1px 3px;
    font-size: 12px;
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
    border-radius: 3px;
    }
    pre {
    display: block;
    padding: 14px;
    margin: 0 0 18px;
    line-height: 16px;
    font-size: 11px;
    border: 1px solid #d9d9d9;
    white-space: pre-wrap;
    word-wrap: break-word;
    }
    pre code {
    background-color: #fff;
    color:#737373;
    font-size: 11px;
    padding: 0;
    }
    @media screen and (min-width: 768px) {
    body {
    width: 748px;
    margin:10px auto;
    }
    }
    </style>
    <title>Writing Tools Writeup.html</title>
    </head>
    <body>
    <h1>Digital Toolchain for Book Authors</h1>

    <h2>Text markup and structure</h2>

    <ul>
    <li>So many light markup formats to consider

    <ul>
    <li><a href="http://daringfireball.net/projects/markdown/">Markdown</a></li>
    <li><a href="http://www.textism.com/tools/textile/">Textile</a></li>
    <li><a href="http://www.methods.co.nz/asciidoc/">Asciidoc</a></li>
    <li>Most compile to HTML, PDF, <a href="http://www.docbook.org/">DocBook</a></li>
    </ul>
    </li>
    <li>Get handy with <a href="http://johnmacfarlane.net/pandoc/">PanDoc</a> (but man, the haskell bootstrapping is a pain)</li>
    <li>List of formats:

    <ul>
    <li><a href="http://en.wikipedia.org/wiki/Lightweight_markup_language">Wikipedia Markup Formats</a></li>
    <li>Prefer AsciiDoc due to its ability to output DocBook</li>
    <li>Markdown is nicely rendered by GitHub and other desktop tools, but really isn&rsquo;t a full book authoring format.</li>
    </ul>
    </li>
    <li><a href="http://orgmode.org">We used OrgMode for outlines and planning</a></li>
    <li>We used Dropbox for syncing it all</li>
    <li>We used <a href="http://daringfireball.net/projects/markdown/">Markdown</a> for any quick write-ups and to-be-integrated raw pieces stored in a separate directory

    <ul>
    <li>QuickLook plugins for Markdown on MacOSX exist. Very nice.</li>
    <li>Markdown editors now exist for the iPad, iPhone and Desktop</li>
    <li><a href="http://mouapp.com/">Mou (Desktop)</a></li>
    <li><a href="http://jblevins.org/projects/markdown-mode/">Markdown Mode (Emacs)</a></li>
    <li><a href="http://www.secondgearsoftware.com/elements/">Elements (iPad, iPhone)</a></li>
    </ul>
    </li>
    </ul>


    <h2>Format, Authoring Tools</h2>

    <ul>
    <li>Scribe

    <ul>
    <li>This is a wrapper over AsciiDoc to easily produce PDF, HTML, DocBook</li>
    <li><a href="https://github.com/schacon/git-scribe-template">Scribe Template</a></li>
    <li><a href="https://github.com/schacon/git-scribe">Scribe Engine</a></li>
    <li><a href="https://github.com/jasonm/guard-git-scribe">Guard for Scribe</a></li>
    <li>Has a few bugs that will be getting love in the next few months</li>
    </ul>
    </li>
    <li>Your Own Toolchain

    <ul>
    <li><a href="http://rake.rubyforge.org/">Rake</a> script for <a href="http://presentationpatterns.com">Presentation Patterns</a></li>
    </ul>
    </li>
    <li>Will try to OSS some of this stuff in the Spring and I&rsquo;ll be hacking on Scribe as I give more time to <a href="http://github.com/training">GitHub employment</a></li>
    <li>XML

    <ul>
    <li>For pure XML (DocBook) authoring, I liked:

    <ul>
    <li><a href="http://www.oxygenxml.com/">Oxygen</a></li>
    <li><a href="http://www.xmlmind.com/xmleditor/">XMLMind</a></li>
    <li><a href="http://www.thaiopensource.com/nxml-mode/">Emacs nXML mode</a></li>
    </ul>
    </li>
    <li>Some of these have DocBook stylesheets built in or a live editor</li>
    </ul>
    </li>
    <li>The drawback to AsciiDoc is the lack of not having the full DocBook tag vocabulary

    <ul>
    <li>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.</li>
    </ul>
    </li>
    </ul>


    <h2>Inline Code Samples</h2>

    <ul>
    <li>Q: Code insertion (such that it can be tested)</li>
    <li>AsciiDoc uses pygments to style the most common languages

    <ul>
    <li><a href="http://pygments.org/">Pygments Homepage</a>. Also used internally at GitHub</li>
    <li>More or less built-in to <a href="http://www.methods.co.nz/asciidoc/">Asciidoc</a> toolchain</li>
    </ul>
    </li>
    <li>Nest the examples as a Git submodule within the Git scribe book or other book technology. You can OSS the examples early. <a href="https://github.com/gradleware/oreilly-gradle-book-examples">We did with Gradle</a>.</li>
    </ul>


    <h3>Example code in Asciidoc (standalone files)</h3>

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

    <h2>Audited version history</h2>

    <ul>
    <li>Q: Naturally, we both prefer Git</li>
    <li>Git, without a doubt, but with more than just a master branch

    <ul>
    <li><a href="https://makandracards.com/makandra/527-squash-several-git-commits-into-a-single-commit">Squash branch commits</a> for bigger &ldquo;units of work&rdquo;, not noisy commits which some of my co-authors seem to like to create</li>
    </ul>
    </li>
    <li><a href="http://jenkins-ci.org">CIed</a> book build</li>
    <li>Used just shell scripts and cron</li>
    <li>Or trigger on Mac folder changes with <a href="http://www.noodlesoft.com/hazel.php">Hazel</a></li>
    </ul>


    <h2>Inline comments and threads/discussions</h2>

    <ul>
    <li>Q: GitHub comments?</li>
    <li><a href="http://www.docbook.org/tdg/en/html/remark.html">Remarks DocBook tags</a> in the DocBook files (Presentation Patterns)

    <ul>
    <li>http://www.docbook.org/tdg/en/html/remark.html</li>
    <li>I wrote and had <a href="http://ambientideasphotography.com">my brother, a JS and HTML guy</a>, write an awesome stylesheet that made the remarks pop in Red.</li>
    <li>Remark tags generate &ldquo;notes&rdquo; in PDFs. Awesome.</li>
    <li><code>TODO</code> keyword in the text with a build script that found and listed them all (like an <code>ack</code>)</li>
    </ul>
    </li>
    </ul>


    <h2>Outlining strategy/hacks</h2>

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


    <p>So, how can this be done in a more reasonable way?</p>

    <ol>
    <li>Level one bullets only. Revise. Review.</li>
    <li>Write 5% of the book based on passion.</li>
    <li>Level two bullets. See impact on level 1. Revise. Review.</li>
    <li>Consider the outline locked unless there is something massively broken.</li>
    <li><a href="http://www.mywritingmylife.com/2011/11/on-writing-the-shitty-first-draft.php">Write a crappy first draft</a> with high velocity.</li>
    <li>Stick to the outline. If you need to change it, change it, but don&rsquo;t let the prose drive the plan.</li>
    </ol>


    <h2>Writing Hacks</h2>

    <ol>
    <li>Use <a href="http://www.nuance.com/for-individuals/by-product/dragon-for-mac/dragon-dictate/index.htm">Dragon Dictate</a> and a <a href="http://www.plantronics.com/us/product/audio-995">Plantronics wireless boom mic</a>. Thank me later. I cranked out 5200 words in a day with it. And you can listen to music while you dictate.</li>
    <li><a href="http://forums.pragprog.com/forums/235/topics/9874">Write every day</a>. Even if just a little bit. I am the worst offender of this advice, but I am trying to stick to it.</li>
    </ol>


    <h2>Task tracking</h2>

    <ul>
    <li>Q: We&rsquo;ve been evaluating <a href="http://trello.com">trello.com</a>

    <ul>
    <li><a href="http://www.youtube.com/watch?feature=player_embedded&amp;v=aaDf1RqeLfo">Demo video</a></li>
    </ul>
    </li>
    <li><a href="http://orgmode.org/">OrgMode</a>

    <ul>
    <li>Emacs major mode

    <ul>
    <li>http://orgmode.org/</li>
    </ul>
    </li>
    <li><a href="http://orgmode.org/guide/index.html">Filter</a> by person assigned

    <ul>
    <li>http://orgmode.org/guide/index.html</li>
    </ul>
    </li>
    <li>Used for almost everything in the <a href="http://presentationpatterns.com">PPAP</a> planning and assignment process</li>
    </ul>
    </li>
    </ul>


    <h3>Sample of OrgMode (Raw)</h3>

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

    <h2>Big Thoughts</h2>

    <p>Hope that helps.</p>

    <p>Matthew McCullough<br/>
    <a href="mailto:[email protected]">[email protected]</a><br/>
    <a href="http://ambientideas.com/blog">http://ambientideas.com/blog</a><br/>
    <a href="mailto:[email protected]">[email protected]</a><br/>
    <a href="http://github.com/training">http://github.com/training</a><br/>
    <a href="http://twitter.com/matthewmccull">@matthewmccull</a></p>
    </body>
    </html>
  5. @matthewmccullough matthewmccullough revised this gist Jan 13, 2012. No changes.
  6. @matthewmccullough matthewmccullough revised this gist Jan 13, 2012. 1 changed file with 2 additions and 1 deletion.
    3 changes: 2 additions & 1 deletion Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -70,7 +70,8 @@
    * Q: GitHub comments?
    * [Remarks DocBook tags](http://www.docbook.org/tdg/en/html/remark.html) 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.
    * I wrote and had [my brother, a JS and HTML guy](http://ambientideasphotography.com), 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
  7. @matthewmccullough matthewmccullough revised this gist Jan 13, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -34,7 +34,7 @@
    * For pure XML (DocBook) authoring, I liked:
    * [Oxygen](http://www.oxygenxml.com/)
    * [XMLMind](http://www.xmlmind.com/xmleditor/)
    * Emacs nXML mode
    * [Emacs nXML mode](http://www.thaiopensource.com/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.
  8. @matthewmccullough matthewmccullough revised this gist Jan 13, 2012. 1 changed file with 6 additions and 3 deletions.
    9 changes: 6 additions & 3 deletions Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -83,6 +83,12 @@ So, how can this be done in a more reasonable way?
    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](http://www.mywritingmylife.com/2011/11/on-writing-the-shitty-first-draft.php) 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](http://www.nuance.com/for-individuals/by-product/dragon-for-mac/dragon-dictate/index.htm) and a [Plantronics wireless boom mic](http://www.plantronics.com/us/product/audio-995). 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](http://forums.pragprog.com/forums/235/topics/9874). 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](http://trello.com)
    @@ -106,9 +112,6 @@ So, how can this be done in a more reasonable way?
    ** Final Draft <2012-02-15 Wed> :nf:mm:ns:

    ## Big Thoughts
    1. Use [Dragon Dictate](http://www.nuance.com/for-individuals/by-product/dragon-for-mac/dragon-dictate/index.htm) and a [Plantronics wireless boom mic](http://www.plantronics.com/us/product/audio-995). Thank me later. I cranked out 5200 words in a day with it. And you can listen to music while you dictate.
    2. [Write a crappy first draft](http://www.mywritingmylife.com/2011/11/on-writing-the-shitty-first-draft.php) with high velocity.
    3. Stick to the outline. If you need to change it, change it, but don't let the prose drive the plan.

    Hope that helps.

  9. @matthewmccullough matthewmccullough revised this gist Jan 13, 2012. 1 changed file with 4 additions and 4 deletions.
    8 changes: 4 additions & 4 deletions Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -2,10 +2,10 @@

    ## Text markup and structure
    * So many light markup formats to consider
    * Markdown
    * Textile
    * Asciidoc
    * Most compile to HTML, PDF, DocBook
    * [Markdown](http://daringfireball.net/projects/markdown/)
    * [Textile](http://www.textism.com/tools/textile/)
    * [Asciidoc](http://www.methods.co.nz/asciidoc/)
    * Most compile to HTML, PDF, [DocBook](http://www.docbook.org/)
    * Get handy with [PanDoc](http://johnmacfarlane.net/pandoc/) (but man, the haskell bootstrapping is a pain)
    * List of formats:
    * [Wikipedia Markup Formats](http://en.wikipedia.org/wiki/Lightweight_markup_language)
  10. @matthewmccullough matthewmccullough created this gist Jan 13, 2012.
    120 changes: 120 additions & 0 deletions Writing Tools Writeup.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,120 @@
    # Digital Toolchain for Book Authors

    ## Text markup and structure
    * So many light markup formats to consider
    * Markdown
    * Textile
    * Asciidoc
    * Most compile to HTML, PDF, DocBook
    * Get handy with [PanDoc](http://johnmacfarlane.net/pandoc/) (but man, the haskell bootstrapping is a pain)
    * List of formats:
    * [Wikipedia Markup Formats](http://en.wikipedia.org/wiki/Lightweight_markup_language)
    * 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](http://orgmode.org)
    * We used Dropbox for syncing it all
    * We used [Markdown](http://daringfireball.net/projects/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)](http://mouapp.com/)
    * [Markdown Mode (Emacs)](http://jblevins.org/projects/markdown-mode/)
    * [Elements (iPad, iPhone)](http://www.secondgearsoftware.com/elements/)

    ## Format, Authoring Tools
    * Scribe
    * This is a wrapper over AsciiDoc to easily produce PDF, HTML, DocBook
    * [Scribe Template](https://github.com/schacon/git-scribe-template)
    * [Scribe Engine](https://github.com/schacon/git-scribe)
    * [Guard for Scribe](https://github.com/jasonm/guard-git-scribe)
    * Has a few bugs that will be getting love in the next few months
    * Your Own Toolchain
    * [Rake](http://rake.rubyforge.org/) script for [Presentation Patterns](http://presentationpatterns.com)
    * 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](http://github.com/training)
    * XML
    * For pure XML (DocBook) authoring, I liked:
    * [Oxygen](http://www.oxygenxml.com/)
    * [XMLMind](http://www.xmlmind.com/xmleditor/)
    * 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](http://pygments.org/). Also used internally at GitHub
    * More or less built-in to [Asciidoc](http://www.methods.co.nz/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](https://github.com/gradleware/oreilly-gradle-book-examples).

    ### 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](https://makandracards.com/makandra/527-squash-several-git-commits-into-a-single-commit) for bigger "units of work", not noisy commits which some of my co-authors seem to like to create
    * [CIed](http://jenkins-ci.org) book build
    * Used just shell scripts and cron
    * Or trigger on Mac folder changes with [Hazel](http://www.noodlesoft.com/hazel.php)

    ## Inline comments and threads/discussions
    * Q: GitHub comments?
    * [Remarks DocBook tags](http://www.docbook.org/tdg/en/html/remark.html) 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`)

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

    ## Task tracking
    * Q: We've been evaluating [trello.com](http://trello.com)
    * [Demo video](http://www.youtube.com/watch?feature=player_embedded&v=aaDf1RqeLfo)
    * [OrgMode](http://orgmode.org/)
    * Emacs major mode
    * http://orgmode.org/
    * [Filter](http://orgmode.org/guide/index.html) by person assigned
    * http://orgmode.org/guide/index.html
    * Used for almost everything in the [PPAP](http://presentationpatterns.com) 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:

    ## Big Thoughts
    1. Use [Dragon Dictate](http://www.nuance.com/for-individuals/by-product/dragon-for-mac/dragon-dictate/index.htm) and a [Plantronics wireless boom mic](http://www.plantronics.com/us/product/audio-995). Thank me later. I cranked out 5200 words in a day with it. And you can listen to music while you dictate.
    2. [Write a crappy first draft](http://www.mywritingmylife.com/2011/11/on-writing-the-shitty-first-draft.php) with high velocity.
    3. Stick to the outline. If you need to change it, change it, but don't let the prose drive the plan.

    Hope that helps.

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