[OpenWalnut-Dev] AsciiDoc: the future of OpenWalnut documentation

[Sebastian Eichelbaum]

Hi Guys,

I was as busy as a beaver and made myself some thoughts about the future of user- and developer documentation in OpenWalnut itself, on the website, and in the packaged distributions. As you might know, we are working on a new and polished website and this is our chance to unify our docs somehow (we have to rework it in any case).

I came across several doc languages and systems, but only two of them left a mark ... namely DocBook and AsciiDoc. Both of them are very mature and actively developed language specifications with a broad variety of tools to transform the documentation in DocBook/AsciiBook language into Latex,HTML,MAN. AsciiDoc and DocBook are fairly similar in their possibilities but two points convinced me to prefer AsciiDoc:

+ AsciiDoc uses a Wiki-Style syntax -> less effort to transfer our online docs and far more readable code
- DocBook uses XML and complex Docs tend to get a syntactical mess

Some advantages when using a markup language for documentation:

+ Doc can be managed in a VCS
+ Can be translated to different target formats automatically
+ Doc can be embedded into OpenWalnut and the website directly
-> Write once, use wherever useful

If you have strong arguments against AsciiDoc, please let me know. If not, the documentation transfer to AsciiDoc will be part of the OpenWalnut 2.0 roadmap.

Thats it from my side.

See you,
Sebastian

-- 
Dipl.-Inf. Sebastian Eichelbaum
Universität Leipzig
Institut für Informatik
Abteilung Bild- und Signalverarbeitung
PF 100920
D-04009 Leipzig