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 [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/turbogears.
For more options, visit https://groups.google.com/d/optout.
