Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Ticket #2355 (closed documentation: migrated)

Opened 10 years ago

Last modified 8 years ago

Documentation Updates and Upgrades

Reported by: pedersen Owned by: pedersen
Priority: normal Milestone: 2.1 docs
Component: TurboGears Version: 2.0b7
Severity: normal Keywords:
Cc:

Description

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:

  1. 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.
  1. 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.

  1. 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.

  1. 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.

Change History

comment:1 Changed 10 years ago by Chris Arndt

Ticket #2230 is related. Maybe merge the two?

comment:2 Changed 10 years ago by jorge.vargas

  • Milestone set to 2.1 docs

comment:3 Changed 8 years ago by pedersen

  • Status changed from new to closed
  • Resolution set to migrated
Note: See TracTickets for help on using tickets.