#2355: Documentation Updates and Upgrades
---------------------------+------------------------------------------------
Reporter: pedersen | Owner: pedersen
Type: documentation | Status: new
Priority: normal | Milestone:
Component: TurboGears | Version: 2.0b7
Severity: normal | Keywords:
---------------------------+------------------------------------------------
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.
2. 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.
3. 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.
4. 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.
--
Ticket URL: <http://trac.turbogears.org/ticket/2355>
TurboGears <http://www.turbogears.org/>
TurboGears front-to-back web development
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google
Groups "TurboGears Tickets" group.
This group is read-only. No posting by normal members allowed.
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/turbogears-tickets?hl=en?hl=en
-~----------~----~----~----~------~----~------~--~---
