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 #1623 (closed enhancement: fixed)

Opened 11 years ago

Last modified 9 years ago

Improve online documentation front page

Reported by: chrisz Owned by: Chris Arndt
Priority: high Milestone: irrespective
Component: Documentation Version:
Severity: major Keywords:
Cc:

Description

The Turbogears online docs are not so bad, but unfortunately they are sometimes hard to find. In particular, the front page should be improved so that the most important doc pages and other overview pages are easier to find.

One of the problems is that the sections have a different hierarchy (as of 2007-12-06). E.g. the "recipes" and "learn" sections are structured with sub-headings, while the other sections are only structured with bullets points which do not appear in the table of contents - e.g. the sub-points of the the "reference" section, though they are very important.

I suggested on the mailing list that this should be changed, with either bullet points used in the learn and recipes sections or sub-headings used in the other sections, too.

Another suggestion on the mailing list was: "I think there is just way too much on that documentation front page, and much of the good information is scattered around. 90% of the stuff that is in the Recipes section should really be rolled into the Reference section. The rest should probably be pushed out to a separate Recipes page. By 'Recipe' I usually think of something like the Python Cookbook, with short snippets to perform quite specific tasks. I don't expect basic guides like 'Identity Management' or 'Overview of SQLObject' to be buried down there. They're fundamental parts of Turbogears and should surely form part of the Reference."

Change History

comment:1 Changed 11 years ago by chrisz

Note: Drafts for the front page should be created here:

 http://docs.turbogears.org/1.0/RoughDocs/WikiOrganization

comment:2 Changed 11 years ago by Chris Arndt

  • Status changed from new to assigned
  • Version 1.0.4b3 deleted
  • Milestone changed from 1.0.4 to __unclassified__

Setting milestone to __unclassified__ and version to empty, since this issue is not really tied to a specific TurboGears release and interferes with the release progress tracking.

comment:3 Changed 11 years ago by randomandy

I made an attempt at reorganizing and cleaning up the 1.0 Doc wiki contents page. I think it is a big improvement over the current sprawl.

 http://docs.turbogears.org/1.0/RoughDocs/WikiOrganizationB

It is a reorganization of all the contents existing on the 1.0 page as of today and consists mostly of moving topics into more sensible groupings. A couple of lists were able to be removed completely because they existed in complete list form on dedicated pages, such as Deployment,and Non Standard Components.

I looked at the previous attempt, which I believe was missing some items existing on the current front page, so I believe it was already out of date. But I looked again today and can no longer find it. I am not sure what happened to it.

If this is acceptable, I urge it be promoted before too many new items are added to the current front page and thus require updates be made to this draft.

comment:4 Changed 11 years ago by Chris Arndt

The new TOC, improved by Andy has now been copied over to the official  1.0 TOC page (leaving out only a few links to yet unfinished docs).

I suggest that we continue to make updates to the RoughDocs page and copy them over to the official TOC from time to time.

comment:5 Changed 11 years ago by Chris Arndt

  • Status changed from assigned to closed
  • Resolution set to fixed

comment:6 Changed 9 years ago by chrisz

  • Milestone changed from __unclassified__ to irrespective
Note: See TracTickets for help on using tickets.