A New Manual In AsciiDoc
Part 1
We are constantly optimizing Merlin Project for easier use. We already started some time ago with the start dialog and cleaning up the inspector.
With version 8, the dynamic help has now been introduced: Just click on the ? symbol and you will get an explanatory help text for every object you point to with the mouse (or with your finger on the iPad). You can even create your own help texts for your own fields.
Unfortunately our manual is a bit behind. But don't worry, there is rich and up-to-date documentation, like:
- A tutorial,
- extensive questions and answers,
- many support articles in this blog
- and of course the dynamic help described at the beginning.
A complete manual does not exist at the moment. And that's exactly what I want to change now.
The Project
I have recently started to rewrite the manual and create this very reference. Of course I have set up a project for it, but unfortunately it has to share the available time with all my other projects.
The Goal
Besides the obvious goal of creating an up-to-date documentation of the features in Merlin Project in the major languages, I set myself a few more sub-goals or sub-objectives:
- The manual must be available as HTML, PDF & eBook.
- Optional Print on demand should be possible.
- The manual should apply to all our products, ie:
- It should be offered for free on our website, iTunes Book store and other sites.
However, the target date is completely open with all planning as I have a different workload from week to week. Thus, it would be completely unrealistic setting a target date.
The Tools
At ProjectWizards, we write all text in ascii format and check it into our git no later than the end of the day.
Quite contrary to the current fashion, we do not write in Markdown or any of its derivatives or supplements. We already focused on AsciiDoc a very long time ago and since a few years on the new Asciidoctor, the new implementation of Dan Allen (via Twitter). The reasons for this decision are mainly:
- Variables,
- Linking other files,
- conditional texts and formatting,
- tables, charts and many other contents,
- text output in many different formats,
- automatic tables of contents, as well as glossaries, indexes and bibliographies
- and much more ...
And before I forget, of course BBEdit is still set as editor #1 with me.
AsciiDoc vs Asciidoctor
In short, you give the AsciiDoc source to Asciidoctor and get a result that you can publish. So:
- AsciiDoc is the language
- Asciidoctor is the processor
Like Markdown, AsciiDoc was designed as a language to be unobtrusive and concise, and to make writing easier, even more enjoyable. But AsciiDoc itself is not a publishing format. It's more like a shorthand. This is where an AsciiDoc processor comes in.
An AsciiDoc processor, such as Asciidoctor, reads the AsciiDoc source text and converts it into publishable formats such as HTML 5, eBook or PDF. Of course, the whole thing is complemented with design tools, such as Cascading Style Sheets (CSS).
Working out Loud (WOL)
In the spirit of Working out Loud I will try to report regularly about this work. I will put less emphasis on how many words or sentences I was able to write during the week. It's much more about presenting help and new knowledge about Asciidoc and Asciidoctor.
With this approach, of course, I also honor the tireless work of Dan Allen and support him. At least as much this is a vote for Asciidoc in project management.
We'll start next Friday at this slot.
