[TYPO3-dev] Re: Extension documentation in ReST format

[Claus Due]

Hi François,

I'm reading, I'm also interested in ReST.

> BTW Claus, if you read this, it is in no way meant as a criticism.

Don't worry about that, I appreciate criticism. Thanks for the kind words about my extensions by the way :)

I also have some (constructive, I hope) comments of my own.

> I fully understand that working with OpenOffice is not only a pain but 
> certainly did not allow you to do what you wanted with your 
> documentation. I just hope that you might find ReST more inspiring ;-)

I most certainly do find it inspiring! I'm already using Markdown and "pandoc" should allow conversion to ReST easily.

That being said, I would just not be able to combine all the documentation at the same time as preserving the overview. Even ReST would be hell to work with, albeit much less than OpenOffice ;)

After all, I'm documenting some 18-20 differently purposed extensions which almost all relate to each other and whose documentation is always relevant for the others. I do include brief offline documentation in every extension (as README.md, Github-markdown, some still incomplete) - just not any format that's displayed on typo3.org. There's the interactive documentation, the ViewHelper references which are generated from code and much more that's just not possible in any file-based documentation format.

I will happily provide ReST versions of the README.md files if ReST becomes supported. But I could not make that the only documentation, hope you understand why :)

I'll keep reading here although I don't have much to add, not having investigated ReST at all. Far too little time left over :/

Cheers,
Claus

PS: Google is obsessive about caching links to old documentation on TER. In my opinion, that hurts so much more than it helps. Perhaps it can be solved by clearly indicating in online docs when they are not related to the latest version - but it's still a pretty bad situation, this having old docs lingering around as top-rated Google links. That too is a reason why I no longer include online-renderable docs for TER.