[SciPy-dev] docs.scipy.org -- new site for the documentation marathon

jh@physics.uc... jh@physics.uc...
Mon Oct 27 14:16:14 CDT 2008


I like the Sphinx site!

But, I like the scipy.org/Documentation URL, since docs are part of
the package and not a separate project (like, say, ipython.scipy.org).
We should have a consistent layout of URLs, so that things that are
part of numpy/scipy are under http://scipy.org/ and things that are
not might still be hosted on a scipy.org domain but are not directly
under http://scipy.org/.  Is it technically possible/feasible for a
Moin site to (appear to) include another site underneath it?  If not,
I'd choose function over form, grudgingly.

For the top page layout, I propose (rationale below):

(No left sidebar)
------------------------------------------------------------
DOCUMENTATION EDITOR
Write, review, or proof the docs!

MATURE DOCUMENTS

Guide to Numpy
PDF book by Travis Oliphant

DOCUMENT-IN-PROGRESS SNAPSHOTS

Numpy Reference Guide (as of yyyy-mm-dd)
PDF   zipped HTML
  refguide glossary shortcut

Numpy User Guide (as of yyyy-mm-dd)
PDF   zipped HTML

Scipy Reference Guide (as of yyyy-mm-dd)
PDF   zipped HTML

SEE ALSO

SciPy.org
all things NumPy/SciPy (bug reports, downloads, conferences, etc.)

SciPy.org/Documentation
more documentation not (yet) in the right format for this site

SciPy.org/Cookbook
live, user-contributed examples and recipes for common tasks
------------------------------------------------------------

Rationale: We have had a real problem getting a critical mass on doc
writing.  We rallied in the summer, but for the past two months almost
no contributions have been made (click on stats to see).  Originally,
the only purpose of the site was editing the docs, and someone who
wanted to read what was current did that through our editing
infrastructure.  This made it very encouraging to edit.  Now, when
they click on "improved docstrings" on scipy.org/Documentation, they
instead go to a passive presentation of the current content, no
editor.  They have to go to the last link on the page to get into the
editor, and the text there doesn't scream "Editor!".  Until we have
*at least* version 1 of each of our docs, we should keep the edit link
first.  I'm almost ready to say the docs in progress should *only* be
accessible through the editor (which does present HTML, zipped HTML,
and PDF) until we have version 1 done.

We should also remove irrelevant links and text.  The Developer Zone
and its instructions for reporting bugs have their own section of the
main web site and are not docs, so they don't belong here.  The
content of the left sidebar is redundant and wastes space.  The
download links should go under the live-doc links, as above, since
this format is easier to read than that on the download page and there
really isn't any other content on this page.  Scipy.org is either a
see-also or nonexistent, depending on whether we can get this page to
appear under it.  The glossary shortcut is also accomodated above.

--jh--


More information about the Scipy-dev mailing list