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

[jh at physics.ucf.edu]

>> 2008/10/27  <jh at physics.ucf.edu>:
>>> But, I like the scipy.org/Documentation URL, since docs are part of
>
>> There is one big advantage to docs.scipy.org -- it is short and easy
>> to remember.  In other words, from the user's point of view: "Where
>> would I expect the docs to be?" "Probably at doc(s).scipy.org or
>> scipy.org/doc(s)".

How about, go to scipy.org and click on the giant doc image at the top
or the Documentation item on the left, just as for every other major
topic?

> It's also easy to Google with site:docs.scipy.org

site:scipy.org/Documentation works just as well.  If you don't like
the length of the word "Documentation", I'm all for shortening it to
docs.

I actually don't have a strong preference between docs.scipy.org and
scipy.org/docs PROVIDED that it's consistent with the other URLs on
the site.  Consistency makes it easiest for new users to understand
the site as a whole, gives an impression of professionalism, and tends
to push out the date when you have to scrap everything and start over.

Right now, each major project has an xxx.scipy.org domain, with all
its stuff (install, docs, download, etc.) below that.  As the flagship
products, the numpy and scipy projects are on the eponymous portal
domain.  If we promote some of the portal's top-level links to project
status, it prevents doing the same for, say, ipython's site sections
of the same name, and also confuses users, who can't figure out why
it's docs.scipy.org but scipy.org/Cookbook.  It also sends the message
that docs are a different project from numpy, which I think is a poor
message to send.

On the other hand, we could think of an arrangement where all projects
can use the doc-wiki infrastructure, share the same cookbook, have a
common set of bug-reporting instructions and download pages, etc.
Then we can make cookbook.scipy.org, download.scipy.org,
bugs.scipy.org, install.scipy.org (that sounds nice! maybe we should
say "document.scipy.org" as a subliminal suggestion...ok, maybe not),
and so on, and see stuff for numpy, scipy, ipython, etc. in each area.
I just don't understand special-casing docs in the scipy.org site
layout.  If this reorg makes sense for docs, let's do it for the
others.  If not, then not.

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

I want the editor to be the first link.  That was the purpose of the
wiki and we have a real problem getting enough people to help (thanks
to all who have, and keep it up!).  I think that mature docs should be
ahead of immature ones.  So that's why to split them.  Once the numpy
and scipy reference manuals and the user guide are complete, we can
move the editor link down to the top of the snapshots.  My $0.02.

> The problem is that presently not all pages are editable via the 
> documentation wiki, only the docstrings,

Ok, good point.  Let's keep the download links.  I don't really want
to separate people from the info they seek, I just want to get them
writing.

Hey everyone!  Write!  Write!  We're over 60% of the way to a good
first draft!  Write!  ;-)

--jh--