sample .asciidoc article for tryouts

testdoc-jb.asciidoc

How to document gracefully

jb …​ trying out some stuff.

Avoid jazzy authoring tools

• stay clear of using bloated sofwares that make jazy promises.

• that use classical UI to produce good documentents.

• that use complicated keyboard shortcuts.

Once you have done about a 1000 select clicks, mouse over, click, drag click, click drags, and you doc still looks like it took a granade, you’ll understand.

Use simple tools

Use Testpad, use Vim, or just use plain old Notepad. They are more productive, let you organize in your head rather than program and the features it offers decide you your art.

Use a markup

When I say use mark up, don’t head over to XML / DocBook. They are meant for machines. Use something meant for humans: json, haml and now ascidoc.

And yea, it in ruby

do:

gem install asciidoctor

then

asciidoctor -d HTML <filename>

will render a HTML document out of your markup.

asciidoctor -d DOCBOOK <filename>

to get a DOCBOOK xml for you article.

Organize well

Finally, It’s all about how you put it together. Nope, the Word won’t think for you, it’ll just make promises and get in the way.

'what say?'.