← Back to team overview

ooc-dev team mailing list archive

Re: Our documentation system


On 12.07.2010 02:18, Amos Wenger wrote:
> As ooc-lang.org's redesign progress, we might even think of some level of
> integration between the blogging/articles
> feature of the website and the docs (e.g. dead easy linking) - I'm looking
> forward to reading your ideas on that.

Sounds like a good idea!

> So basically here are the requirements for a new doc system:
>     - Easy to use. It might even take a glob of .ooc files and call rock
>     -backend=json itself, by default
>     - Javadoc/Doxygen syntax with Markdown-improved (e.g. implicit URLs,
>     etc.) for formatting
> - Beautiful. Doc is boring - if the generated doc is pretty enough that
>     it makes someone *want* to read it - bingo.
> - Easy to navigate. Pretty much everything should be clickable. ooc code
>     should be highlighted. (Opt-out) links to .ooc source files (colored
>     versions, anchor links?)

That would cover the API documentation. Then again, what do we do about the hand-written documentation?



Follow ups