Tooling


 

I've been putting some thought into tooling and I've come away thinking that I'd like to try Gitbook and use AsciiDoc (not Markdown) for the book. There's a fairly low barrier to entry for others contributing and I think it would be featureful enough to write a book. I'd consider doing Markdown. Talking to Steve Klabnik who is the driving force behind the Rust Book, it sounds like its working for them. Personally, I always get frustrated with Markdown for anything beyond the most basic of formatting. If you have suggestions for other possibilities, I'm open to them.

GitBook's ability to generate PDF, ePub, mobi or a website is a big selling point for me.

Things, for various reasons, that I am very much against using:

  • MS Word, Pages et al
  • Latex et al
  • Google docs

Let me know if you have other alternatives that should be considered...

-Sean-


 

I completely agree that plain text mark up languages for documentation are the way to go. They stay out of the way when you are writing, and make collaboration and merging much simpler.

I use Markdown regularly for things like online doc, papers and wikis, and it's great for that. I haven't written anything as large as a book before, but AsciiDoc appears to addresses larger doc requirements better than Markdown.

Sounds like AsciiDoc is the way to go.