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

[Alexander Wiebel]

Hi Sebastian,
this seems to be a very good idea. I also prefer wiki syntax because it
seems much more readable and we do not need so many sophisticated features.

Cheers
Alex

On 02/13/2014 11:42 AM, Sebastian Eichelbaum wrote:
> 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
>