Documentation SIG
Index
Current Status
Subscribing
Maillist Archives
About Python SIGs
 
Tools
HappyDoc
pythondoc
Structured text rules
HTMLgen
Other Languages
 
Email Us
doc-sig-owner@python.org
 
 
© 2005
Python Software Foundation
  

Documentation SIG Status

Emerging Products

The Doc SIG members have produced some tools:

  • HTMLgen is now available from Robin Friedrich's starship website, as well as from the Python ftp site (that's a gzipped tar file; possibly an older version).
  • Doug Hellmann has created HappyDoc, a tool for extracting documentation from Python source code. It differs from other such applications by the fact that it uses the parse tree for a module to derive the information and does not import the module.
  • Daniel Larsson's pythondoc package is on starship.
  • Daniel's older gendoc package is also on starship.

Structured Text

Early discussions generated the "Structured Text" proposal; the details of this format are described in Structured Text Formatting Rules. This proposal does not hold any "official" status.

Continuing questions

The doc-sig discussion should focus on coming to an agreement on the types of documents that are needed, the format that documentation should be made available in, and the content or subject matter that should be covered in those document. The project should also make an effort to recruit authors. Examples of options available include:
  • Types of documents:
    • Tutorials and HowTo Papers
    • User Guides
    • Reference Manuals
    • Installation Guides
    • Text books
    • Books of documented examples
  • The format options:
    • Write in one format, and generate multiple output formats.
      • Linuxdoc
      • Bill Janssen suggested something else
    • What output formats are needed
      • Postscript
      • HTML
      • info
      • troff (-man option)
      • native Grail .pyc files ??
  • Subject matter:
    • Python core
    • Extension modules
    • Applications
    • Applets

THE PSA as a Catalyst

Authors of software would have an incentive to write documentation according to a common standard if that were a prerequisite for receiving the PSA stamp-of-approval. For this to work the PSA will need guidelines to use for the evaluation process. The review guidelines may include things such as:
  • Form and content rules
  • A style guide
  • Suggested tools such as syntax and spelling checkers
  • Document review process
    • review goals
      • completeness in regards to type and content of documents
      • content evaluation for redundancy with existing documents
      • content evaluation for inconsistency with existing documents
    • Qualifications for proofreader
Having the PSA perform this function of course assume someone is willing to volunteer or to pay for having documents reviewed. The PSA stamp would be the carrot. The incentive for participation is quid pro quo. It should work for a range of circumstances. For instance:
    in the commercial world:
    Presumably companies would be willing to undergo the review process just to get a neutral party's editorial comments on the quality of their products. This would help them improve the products. There are many examples where a stamp on a product is used by customers in making the decision to purchase a product. Generally if the stamp is equated with a noticeably higher quality products it will have more weight in the decision.
    in the academic world:
    Peer review is key to obtaining and retaining a position at many universities and research organizations. Being asked to be an editor is as valued as being approved by the peer review process. Presumably the PSA's stamp and publication in the PSA archives would be considered equivalent to publishing in a peer reviewed journal. Both editors/reviewers and authors would be interested in contributing if the PSA became a vehicle for peer recognition.
    in the free-ware world:
    They'll do what they want anyway, but in general the goal of writing free-ware is for personal satisfaction, for the glory it brings, or to achieve fame. In all cases having a stamp will enhance the work.

    The problem for this group is that finding reviewers will be difficult. Who will pay for the review? Growing a large PSA membership from the general population is important to solving this problem. Reviewers could be paid out of receipts from membership dues if the organization is big enough. As an incentive for being a member you would be given access to the products list and documentation on products that have the official stamp.