Documentation Updates and Upgrades

[pedersen]

This issue existed in Trac. The original can be viewed at http://trac.turbogears.org/ticket/2355

This issue existed on SourceForge. The original can be viewed at https://sourceforge.net/p/turbogears2/tickets/25

[pedersen]

Original Author: pedersen, Original Timestamp: 2011-03-27 20:41:53.085000

Original Body: This ticket is being made by me mostly to track the various phases of the documentation upgrade process. I realized a few minutes ago that I had only documented the current update plans in unofficial places (email and IRC). This provides a concrete reference for me.

The docs have, really, a few major problems. In order of importance:

Organization (or lack thereof). The current organization makes it very difficult to find something. You start up, read the docs, and then a month later find you need something that you read a month ago. Finding it again is nearly impossible, and this is due to the way the docs are organized. The new version of the docs will have significantly better organization, as you can already see. 

Unknown holes in the docs. When looking at the current docs, it's easy to find several items labeled as "Write this up" or "XXX: Get this done" or "TODO: Write me" type things. Sphinx, the tool that produces the HTML docs, provides support for a todo list. During my reorganization, I'm going over every single file looking for these holes, and making actual todo list entries. If you go to http://web.icelus.tzo.com/~marvin/tg2/todo.html you will see the current full todo list. 

    Once we have all the holes identified, we'll be organizing a doc sprint to plug those holes. Hopefully, with only one or two of those (plus some concerted effort by yours truly), we can get the todo list cleared out entirely within a month or so.

Bad code in the docs. I've seen it in there already, and fixing all of it right now is not a quick process. The reorganization is helping me to spot the issues, but we actually have places where shell commands are listed as code blocks, as are HTML fragments, and the like. All of these have to be cleaned up. 

    Basically, once 1 and 2 are done, this is the next task. The goal here will be to turn all code fragments into items that pass automated testing, and then keep them there.

Finally, inconsistent templates. Some pages list a status, or an intended audience, and others dive right into the topic at hand. Once 1, 2, and 3 are done, I'll be introducing actual templates, deployed using Paster, to bring the docs into a consistent look and feel regardless of page. 

---

09/30/09 03:28:20 changed by Chris Arndt

Ticket #2230 is related. Maybe merge the two?
Delete 11/17/09 10:10:53 changed by jorge.vargas

milestone set to 2.1 docs.

[pedersen]

Original Author: pedersen, Original Timestamp: 2012-08-24 01:39:47.348000

Original Body: - version: 2.1.0 --> 2.1.5

• milestone: 2.2.0 --> 2.3.0