Ticket #1646 (assigned defect)

Opened 4 months ago

Last modified 3 weeks ago

Documentation Strategy

Reported by: lszyba1 Assigned to: Chris Arndt (accepted)
Priority: high Milestone: 1.1
Component: TurboGears Version: 1.0.4b3
Severity: critical Keywords:
Cc:

Description

Hello, Right now Turbogears biggest problem is no Documentation. We need a strategy from turbogears project to lead a way to better documentation.

What documentation? 1. First step is to setup epydoc and provide documentation that is available in python code. http://epydoc.sourceforge.net/using.html, you have an doc.ini file already http://groups.google.com/group/turbogears-trunk/browse_thread/thread/c6e4776957b75abc put the results in epydoc.turbogears.com 2. Provide one source or one template that has all the documentation pages. Perfect setup is: http://www.sqlalchemy.org/docs/04/index.html template that builds one page documentation. If this is too hard then merge all wiki pages into one rough1.0doc and let people start working on removing duplicate stuff. 3. Provide some limits/proper use on creating wiki pages. Example: Search on widget results in 16 results out of about 1264 pages. (0.79 seconds)

  1. 1.0/CompoundWidgets
  2. 1.0/DataGridWidget
  3. 1.0/IntroductionToWidgets
  4. 1.0/RemoteFormWidgetTutorial
  5. 1.0/RoughDocs/DiveIntoWidgets
  6. 1.0/RoughDocs/ModifyWidgetDefault
  7. 1.0/RoughDocs/WidgetTips
  8. 1.0/RoughDocs/WidgetsOverview
  9. 1.0/SimpleWidgetForm
  1. 1.0/StatelessWidgets
  2. 1.0/WidgetBrowser
  3. 1.0/WidgetList
  4. 1.0/WidgetPackages
  5. 1.0/Widgets
  6. 1.0/WidgetsOverview
  7. 1.0/WidgetsWithJSAndCSS

1.0/Widgets should be only one that holds all subsequent pages as part of the doc.

4. wiki software? Is this a moinmoin wiki? It seems to be really hard for me to edit it because of syntax. Can we switch to moinmoin wiki? python/debian websites are using it and the syntax is much easier. It allows docbook rendering as well as other options that can potentially be useful. Much more syntax options http://wiki.debian.org/ Out current wiki has a similar look but the benefit of more user friendly doc software will benefit us more.

5. Could these changes be implemented before next release? 1.0.x And setup some time frame of what is going to be done, or what can be done now vs next week vs month from now.

Thanks, Lucas

Change History

01/21/08 08:39:07 changed by Chris Arndt

  • milestone changed from 1.0.4 to 1.1.

02/06/08 08:27:21 changed by lszyba1

There has been a conversation in the debian www mailing list and Osamu Aoki from debian.org was able to create an xslt transformation of moinmoin pages to an html/pdf etc. Here is the reference to the results and code: http://wiki.debian.org/DebianReference The code can be downloaded, the make files changed and we could use it to create html/txt/pdf version of our documentation on a wiki. Some questions to answer are: what version of moinmoin are we running? Is the render as docbook available?

Lucas

04/24/08 18:20:20 changed by Chris Arndt

  • owner changed from anonymous to Chris Arndt.
  • status changed from new to assigned.

Yes, the wiki is moin moin. but I don't think that we well switch to MoinMoin? syntax. See the footnote in http://docs.turbogears.org/DocHelp#documentation-format-style-guidelines for reasoning.

But I agree that the wiki has too many pages that cover similar topics but do not quite have the same information, so there is considerable overlap and confusion. A first step in consolidating this has been done through ticket #1623.

While I also think that the SQLObject docs are great, I think their scope is not directly comparable to TurboGears'. In the TurboGears docs we try to ingrate information from many projects. Sometimes I think, this was a bad idea, we should have documented what TurboGears adds properly first.

I think I want to make a fresh start with TG 1.1 and move official docs to the SVN repository and build them with Sphinx. Contributed docs would still be hosted on the wiki and integrated into the official docs when appropriate. If you want to help to plan and carry out this effort, you are very welcome!