The CL Gardeners have proposed a project for providing better documentation for Lisp Packages

Champion

Cody Koeninger is championing this project. Here's his second pass at meeting Peter Seibel's 3 criteria for a 'blessed' project:

Proposal

1. Purpose

Provide user-level documentation for Lisp packages. This is a good idea because many Lisp packages are not immediately usable, due to a lack of adequate documentation.

2. Goals

Meta-goal: A user should be able to start using a 'gardened' lisp package within 10 minutes of beginning to read the documentation.

Sub-goals, in no particular order:

i. Develop Policy

Get a rough agreement on minimum guidelines for what we want to see in documentation. By which I mean "argue on the CL Gardeners list until the volunteers who are interested in documentation come up with a list of criteria, or get tired of it."

ii. Choose Tools

Research documentation tools and recommend a defacto gardeners standard, if that makes sense. We're in no position to be dictating package authors' choice of tool, so the tool needs to be dead-simple and usable on already available docstrings without any extra work by the package author.

iii. Write & Distribute Documentation

When gardeners notice a package with documentation that falls short of one of the guidelines, they write the necessary improvements. The improvements are submitted to the package author(s), perhaps by another gardener responsible for coordination, in a form acceptable to the package authors. Follow up with the authors as necessary.

3. How people can help

• If you're interested in documentation policy, share your thoughts with the gardeners list.
• If you're interested in documentation tools: research one or more of the tools listed below, write up a review, and submit it to the gardeners list.
• If you're interested in writing documentation: find a package that needs gardening, add it & your name to the list below, improve the documentation, submit your improvements (to the gardeners list for now?).
• If you're not interested in any of this, add to the list of packages below the next time you try to use a package & the documentation needs help; we'll look at it.

Volunteers

Cody Koeninger - champion, tool comparison
who else?

Tasks

Compare Tools

Choose a documentation tool from the list of candidates. Use the tool to document itself, and one other package of your choice. Try making at least a minor change in the documentation, to see how it works. Would you want to use this tool as an author? As a reader? Write up your results & send them to the gardeners list for discussion.

• CLDOC Cody, already did partial review, will run it on another package (cl-curl maybe?) and see if there's a way to provide a "start here" sign of some kind.
• Albert Partial review by cody, someone else should pick this up & try running it on a different package.
• Tinaa
• Someone should try out the sbcl tools, from a recent gardeners post: "The SBCL developers, however, have tools for extracting information from source code and generating Texinfo-formatted files that are part of the u See create-contrib-doc-list.lisp and docstrings.lisp in the doc/manual directory of the SBCL source tree."

Comparison of CLDOC and Albert by Cody Koeninger

Erik Enge says:
"In a month or so, common-lisp.net will automatically generate documentation for all projects with a .asd file every night using CLDOC."

Albert has the ability, as demonstrated a while back in a trial run on the Maxima codebase, to generate "called by" information automatically. AFAIK, this ability does not depend on xref. Whatever the "best" choice might be, I would recommend this ability be preserved. (Watch out for the full listing of the Maxima package - it's a very very very large html page.)

Argue about policy

In my opinion, documentation should include:

• Purpose: A brief statement of what problem the package solves, 2 sentences max.
• Usage: Brief example code demonstrating the most common use of the package. This should come early, preferably within the first page, to provide a starting point.
• Installation: Any special instructions on installation.
• Function descriptions: At least a docstring explaining each exported function.
• . . . .

The work of Ed Weitz is given as an example of good documentation (note that Edi does these by -- gasp -- hand!). Personally, I think Edi's great, but that documentation would fail the 10 minute test for me. Turns out it took me exactly 10 minutes to install & reach the point where I could do (cl-ppcre:scan "regex" "target string with regex in it"), but I made a lucky guess that 'scan' was the function I wanted. I'd still hold up well-documented CPAN modules as a better example, because it provides a sample of the most common usage within the very first page of documentation.
Forming a set of standards that aim for this sort of quality may be an important goal.

Identify packages that need documentation help:

---

This page is presently Uncategorized: please add appropriate category markers? and remove this text.