[TYPO3-doc] [reST migration] Getting rid of tables for displaying references

[Oliver Salzburg]

On 2012-03-30 11:50, François Suter wrote:
> Hi all,
> 
> While brainstorming about the migration to reST, one particular point
> came up.
> 
> Until now we have been using tables to present lists of properties, with
> their name, type, description, etc., each in one column. This makes for
> a very compact layout, but not very readable since each column is rather
> narrow (and adding columns would make each even narrower). Long
> descriptions and code samples often end up as long strips of text.
> 
> It would seem like a good idea to replace such tables with text
> sections, just like chapters. To have an idea how this could be
> structured, look at the "solr" extension documentation, which does it
> this way: http://forge.typo3.org/projects/extension-solr/wiki/Tx_solr
> 
> This would have other advantages, beyond improved readability:
> 
> - it would enable us to add information like "Since" and "Removed",
> which we didn't really know where to put until now (adding columns would
> have made them narrower)
> - code examples could be longer
> - it's actually easier to migrate to reST with such a structure, as we
> wouldn't need the "field-list-table" directive which Martin implemented
> for this project, but which is probably isn't going to make into the
> docutils core soon.
> 
> Personally I think this would really be an improvement, even if it means
> having a less compact documentation.
> 
> What's your opinion?
> 
> Cheers

Yes, yes and yes.

Maybe some links for inspiration :)

The past few days I've been digging into ExtJS development and their
documentation follows the same style:
http://docs.sencha.com/ext-js/3-4/#!/api/Ext.tree.TreePanel
I found it to be very organized and easy to skip through. Like it a lot.

And, of course, the very great MSDN .Net documentation:
http://msdn.microsoft.com/en-us/library/system.io.fileinfo.aspx

Cheers
Oliver