[SciPy-dev] Accessible SciPy (ASP) project

[Pearu Peterson]

On Mon, 18 Oct 2004, Joe Harrington wrote:

> DOCUMENTATION
>
<snip>

> 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.
>
> 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.
>
> 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.

I agree that MSWord is out, even OpenOffice or StarOffice would be out 
for me.

Python documentation project is moving from using LaTeX to ReST (note 
that ReST is different form ST). ReST has LaTeX capabilities but only for 
its LaTeX output. But in principle we can generate any desired format 
from LaTeX.

Personally, I would prefer ReST (as the future standard documentation 
tool in Python) or LaTeX (as a very powerful documentation tool in 
general both in past and future). I have put ReST before LaTeX (in other 
cases it would be reversed) because ReST could be used in documentation 
strings as well.

I could use Lyx but I consider it as WYSIWYG-LaTeX which does not impress 
me much when using Auctex Emacs mode in working with LaTeX documents.

As I have understood from earlier discussions that LaTeX may scare people 
away from writing documentation for Scipy. But let me ask may be a bit 
harsh question: are these people able to produce good quality technical 
documentation for Scipy if they reject to learn LaTeX basics? Afterall, 
LaTeX is not that difficult to use, especially when we can provide 
documentation templates to get started easy, and there are nice LaTeX 
frontends available for Windows as well.

> PRIORITIES
>
> The three areas for improvement can proceed in parallel.  Since
> packaging issues affect the documentation, those should be resolved
> as soon as possible.
>
> For packaging, we need to:
>
> 1. determine whether the idea of replacing xplt and gplt with
> matplotlib in the docs is acceptable to the community,

Fine with me (as I am not currently using any of these tools yet).

> 2. determine whether IPython should go into the core,

I am using it on dayly basis, so +1 from me.

> 3. determine whether the "coexistence" approach for resolving the
> numeric/Numarray split is a good idea.

First, we need to get Numarray support to Scipy and then we can make 
decicions on the above.

> Then, we need to roll and field-test the binary packages.  The latter
> effort will require volunteers, so if you want your package or
> platform to be supported, please sign up.
>
> For documentation, we need to agree on a common source format, an open
> copyright, and some stylistic guidelines.  Documents are needed in
> roughly the order listed above, though if someone is very inspired to
> start on a later one, he or she should proceed.  Suggestions for
> additional documents are welcome, as are volunteers to write them.
>
> Goals for the web site are less clear than for packaging and
> documentation.  Some mailing list brainstorming on content and format
> issues would be a good idea, starting with those above.  Then, we need
> to identify page maintainers and get them access.  Several individuals
> stepped forward at the BoF, and a web human interface designer has
> volunteered to help.  Again, more volunteers are needed.

This is good that people offered help at the BoF, but not enough to get 
real work done. I think now we should take the next step and ask specific 
help in person.

Regards,
Pearu