[TYPO3-english] Manual for your own extension

Xavier Perseguers xavier at typo3.org
Mon Jul 28 14:55:04 CEST 2014


Hi Stephen,

> I just updated some extensions and was thinking of re-making my
> documentation, but then is saw what was involved and decided it more
> trouble than it is worth.

Just had a quick look over your extensions and in fact, it would be some
hours of work. I'd say it would be worth the effort (just think about
how easily you could cross-link to TSref since most of your extensions
heavily describe TS configuration of your extensions and thus largely
enhance the UX).

Default rendering (which is already "good", I agree):

http://docs.typo3.org/typo3cms/extensions/scoopit/Scoopit/TyposcriptConfiguration/PlugintxScoopitview/Index.html

With cross-links and new format:

http://docs.typo3.org/typo3cms/extensions/restdoc/Configuration/TxRestdocPi1Setup/Index.html

> If you want something that is easy to edit, can be translated etc. why
> not just let all extension developers create a wiki page?

It's up to you to edit/manage your doc in a wiki. Some authors do that
and TER lets you link to an external manual.

Generally we are convinced Sphinx is a good choice for replacing OOo. Of
course a new format means new tools, new "learning", ... but "backward
compatibility" stays so your existing OOo manuals still work if you
don't want to convert them.

However, seeing recently that new extensions are created with OOo
manuals, and seeing in the long run that more and more extensions are
published without worrying about doing it right with at least some basic
explanation/screenshot of what it does, and how, I felt useful to make
it clear for everyone how an extension should get documented, to make
sure the info is not "hidden".

Kind regards

-- 
Xavier Perseguers
TYPO3 CMS Team Member

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org



More information about the TYPO3-english mailing list