Re: [TurboGears] TurboGears2 Documentation Improvement Suggestions

[Alessandro Molina]

Thanks for the assessment, I actually never downloaded the doc as PDF so I see what's the output for the first time :D

The current TurboGears documentation has been designed around the HTML fruition, and PDF Download only came when it recently got moved to readthedocs.org, so that's why many things might not make sense when downloaded as PDF (like the empty Chapter 6 or the toc depth).

If you want to submit any change to https://github.com/TurboGears/tg2docs I'll gladly review and merge them, any improvement to the documentation is of course welcome :)

On Thu, Nov 19, 2015 at 12:14 AM, Robert James Liguori <glies...@gmail.com> wrote:

I went to Staples tonight and printed and bound the TG2 documentation.  Here are some of my thoughts on the structure of the TurboGears PDF documentation. Note that I know that it's likely auto-generated, but I still wanted to put my two cents in to see if it can influence you guys to improve the printed PDF contents slightly...

[ ] Consider refining the documentation so the PDF could be referenced as the "TurboGears User Guide" vs. the "TurboGears Documentation".

[ ] Provide a more comprehensive Introduction, perhaps in it's own chapter (which would be chapter 1) explaining what TurboGears is and is used for and also its history.  Call out the specific audience of the guide. Chapter 7 (Getting Started) should follow this section as section 2.

[ ] Chapter 6 (The TurboGears documentation) doesn't really make any sense in the printed PDF.

[ ] Consider providing a chapter on project resources links. eg., source code, issue tracker, wiki, social media links, etc.
    Reference1: http://bit.ly/1kFCHKY
    Reference2: Chapter 14 of the Primefaces User Guide: http://bit.ly/1MCpwRJ

[ ] Consider providing a FAQ chapter.  Reference: Chapter 15 of Primefaces User Guide: http://bit.ly/1MCpwRJ

[ ] Consider displaying lower-level sections in the TOC... this would work great for showing the reader all of the basic recipes for example (e.g., 4.2.1 Creating and Validating Forms). Table-Of-Contents Example with lower levels displayed: http://bit.ly/1O3GNYl

[ ] Consider renaming "Basic Documentation" and "Advanced Documentation" chapters to "Basic Features" and "Advanced Features"

[ ] Consider a section listing IDEs that support TurboGears special features

[ ] Consider adding a glossary

[ ] Include a reference to the license(s) of which TG2 uses.

[ ] !!! Review the Flask documentation (http://flask.pocoo.org/docs/0.10/) There's probably lots of stuff here that TurboGears does as well that may not be represented fully in the the TG2 documentation. UPDATE the TG2 documentation accordingly. Also, the PDF version: http://flask.pocoo.org/docs/0.10/.latex/Flask.pdf   Note: I realize this may be a lot of work... but your user community could really use all the info you can give it.

I'm going to do a quick technical review tonight of the user-guide and will post those findings here as well.

I hope this is helpful.

Sincerely,
Robert

--
You received this message because you are subscribed to the Google Groups "TurboGears" group.
To unsubscribe from this group and stop receiving emails from it, send an email to turbogears+...@googlegroups.com.
To post to this group, send email to turbo...@googlegroups.com.
Visit this group at http://groups.google.com/group/turbogears.
For more options, visit https://groups.google.com/d/optout.