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

[Pauli Virtanen]

Hi,

Mon, 27 Oct 2008 15:16:14 -0400, jh wrote:
> 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.

I don't see a problem having a separate domain docs.XXX -- I think it's 
relatively clear to the user what the site contains, and emphasizes that 
this is the "official" documentation. Also, several projects, eg. Python, 
have a similar layout, so I don't think we are in a bad company with 
this). But technically, it would be possible to have scipy.org display 
documents residing on docs.scipy.org (eg. using mod_rewrite [P] in apache 
-- involving Moin in the process is wasteful).

> For the top page layout, I propose (rationale below):
> 
> (No left sidebar)

The branding on the docs site should probabably be made a bit more 
similar to that on scipy.org, and this probably involves deciding what to 
do with the sidebar. There should also be an obvious way back to 
scipy.org. The muse is silent, so I don't know how the page should look 
like now.

> ------------------------------------------------------------
> 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
[clip]

Looks good to me. How about combining the "DOCUMENTATION EDITOR" and 
"SNAPSHOTS" sections?

[clip]
> 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.

It's possible (and easy) to add an edit link on each editable page in the 
static documentation. I can add these.

The changes won't, however, be immediately visible in the static 
documentation, so maybe clicking the link the first time should show a 
popup (or something else easy to implement in static javascript) that 
explains this.

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

The problem is that presently not all pages are editable via the 
documentation wiki, only the docstrings, so for motivation (including 
mine), I think it's important to have a snapshot of the "final" versions 
available somewhere. Maybe not linked to with big letters, but still 
available.

Issue [1] is a blocker for this, and one needs to think also about [2].

.. [1] http://code.google.com/p/pydocweb/issues/detail?id=26
.. [2] http://code.google.com/p/pydocweb/issues/detail?id=27

> We should also remove irrelevant links and text. 
[clip: downloads to main page, remove unnecessary links]

Sure, these seem like good improvements.

-- 
Pauli Virtanen