[SciPy-dev] Accessible SciPy (ASP) project

Janet Swisher swisher at enthought.com
Tue Oct 19 18:08:03 CDT 2004

Some thoughts on documentation:

> -----Original Message-----
> Documentation is undoubtedly the area where the largest 
> number of work hours remain to be done.  It needs rewriting, 
> or writing for the first time, at all levels visible to 
> users.  Because of this and the beta nature of some of the 
> packages, it makes sense to focus on shorter documents that 
> address specific tasks, rather than something like a paper 
> book (though that might make sense two to three years from 
> now). It is important for docs to be well-written: clear, 
> concise, grammatical, current, complete, correct, and 
> visible.  

I am happy to help with the "grammatical" part, and with the "clear,
concise" part for any author who wants suggestions in that area. The
user/developer community are the best ones to create "current, complete,
correct" content for docs, so I applaud this effort. (The "visible" part
should be a result of the web site efforts.) I would definitely encourage
anyone to share their hard-won knowledge, even if they don't have greatest
writing skills. The open source peer review process can hone the text, once
the content exists. 

Focussing on shorter documents also defers one of the factors that can make
otherwise well-written documents less usable: poor organization. A short
document has less opportunity to be poorly structured than a long one. A
collection of short documents can be assembled into a helpful organization
as it evolves.

>Needed documentss:

Some of these documents already exist, but perhaps need to be refocussed. 

> What is SciPy? (listing of features and included packages) 

The FAQ document addresses some of these issues. It doesn't have to retain
its current FAQ structure if that's not helpful. (I have also thought about
using Plone features to add true FAQs.)

> Installing and Testing SciPy on Red Hat Linux
> 				Debian Gnu-Linux
> 				MAC
> 				Windows
> 				Sun
> Getting Started with SciPy

There is a "tutorial", but it is not what I usually think of as a tutorial,
which is a step-by-step walk-through of a basic usage scenario that
illustrates commonly-used functions. The existing tutorial starts out that
way, but becomes more of an overview of each of the sub-packages. 

> SciPy for IDL Users, with cheat sheet
> SciPy for Matlab Users, with cheat sheet
> SciPy User's Guide

The current "tutorial" might morph into a general User's Guide.

> SciPy Reference Manual

The existing API doc is generated using epydoc. The docstrings need much
improvement. This is an area where lots of people could contribute a little
bit. We would need to establish some standards to follow (can of worms, to
be opened later).

> SciPy for Astronomy, Biology, Chemistry, etc.
> It was noted at the BoF that Enthought has substantial 
> documentation in its Windows package in .chm format, and that 
> there is now an X reader for these files.  Those documents 
> will be broken out for non-Windows users and may form the 
> bases for one or more of the documents above, assuming 
> cooperation from Enthought on permissions and copyrights.

Eric has the final word on this, but I would think that any use of existing
content that conforms to SciPy's BSD-style license would be acceptable. We
can probably come up with a documentation-oriented variant of the license,
like FreeBSD has

> Translations are always a good idea, but can only be obtained 
> in a community project through the work of competent 
> volunteers.  The quality of our documentation will be vastly 
> improved by user testing and comment, and by the 
> participation of more than one person in the creation of each 
> document.  However, content determines form, so we should not 
> be shy about making first drafts available, provided that we 
> continue to work on them.

OOoAuthors (http://www.oooauthors.org/) is an example of an open source
documentation project that we might emulate.

> We will need to agree on a set of standards for writing 
> documents. Certainly all docs should be available in PDF and 
> HTML, and the source should be modifiable by anyone on any 
> platform.  The Windows .chm format may also be a viable 
> target if good tools exist to do it under Linux and Mac as 
> well as Windows.  The source form must be viable in the long 
> term and must not leave us in a bind if the text-processing 
> software ceases to be supported.  Structured Text and LaTeX 
> have been suggested.  MSWord and other proprietary forms are 
> out.  The major need for formulae in scientific documentation 
> may push us to LaTeX, perhaps with a standardized format, but 
> this is open for discussion.

For any given tool, there is the burden of learning to use the tool, added
to the cognitive load of actually writing the document. No matter how
popular the tool you pick is, there will be some potential contributors who
aren't familiar with it, and have to pay that extra price in order to
participate. As always, there is also a trade-off in ease-of-use vs. power
and flexibility. To keep the barrier to entry low, it might make sense to
use a simple tool (such as ST or RST) for short documents and a powerful
tool (such as LaTeX or DocBook) for longer documents. Note that short
documents can be created directly on the SciPy.org site using Plone or (with
the Zope ExternalEditor plug-in) in the editor of your choice. On the other
hand, if one of the goals is including these docs in the download packages,
that solution might not meet it. On the third hand, many open source
projects have howtos and such that are available only online.

Thanks, Joe, for contributing the energy and enthusiasm to move this

Janet Swisher
Senior Technical Writer
Enthought, Inc.

More information about the Scipy-dev mailing list