[TYPO3-dev] ReST documentation from extensions

[François Suter]

Hi Dirk,

Thanks for outlining these user stories.

> As an extension developer, I want to:
> - maintain only one version (ReST) of documentation

We are really aiming for that, we are just not at that stage yet, mostly 
for lack of manpower.

> - have an opportunity to inspect the rendering results (as this is the
> most cumbersome part for me in writing documentation nowadays: I was
> never able to predict what my changes in manual.sxw did to the online
> version. There could be a service which renders a preview for both pdf
> and html version)

There is already a service for rendering your docs online. It was mostly 
done by Fabien and I'm not entirely familiar with it.

> As an integrator, I want to have an up-to-date configuration manual of
> each extension available in the backend.

That would be the point of some "documentation" extension, which would 
be used to fetch all manuals from the docs server.

> (And I don't want any undocumented extension in my system nor any
> documentation scattered over a bunch of shiny fancy private/corporate
> websites as this is more and more the case -> for documentation see
> website xyz.com)

I agree with that. I can only hope that the move to ReST encourages 
developers to avoid such behavior in the future.

> As a developer, I want to have an up-to-date api-documentation of each
> extension (online?).

That seems harder to achieve. I don't know if it would be feasible to 
integrate all extensions on api.typo3.org. I rather doubt it, as there 
are so many, with so many versions each. I guess it would be possible to 
write an extension which wraps around some phpDoc parser and creates a 
local API reference. We just need someone motivated enough to do it.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch