On the road to better documentation

Sciter documentation, how to say in polite manner, is not convenient. I know.

So looking for ideas of making it better.

Problem is that I need documentation for at least of two types of media: for Sciter’s help browser and for the web. While I can use HTML it is not always use the same files. Standard CSS is not at Sciter’s level yet.

For example I missed things like flow:row(dt,dd), simply no such things in conventional CSS. <dl/dt/dd> lists are barely usable without proper styling. To achieve flow:row(dt,dd) layout on the web it need to render it as a table, sigh.

So it is clear that documentation shall use some other format and be assembled from it for particular use. One of obvious choices is to use Markdown for that. So I need markdown parser in Sciter that supports hierarchical constructs like <li><pre>… I’ve managed to implement such a parser in 250 lines of code. Just in case, original Perl parser written by John Gruber is about 1400 lines of highly cryptic Perl code. In Sciter I am using generators/yield that allowed to simplify the whole thing.

This is how test-bed looks that far:

And speaking about software documentation in general.

I’d appreciate any examples of good examples of software documentation. But not from Microsoft or Apple please – they are barely readable.