On 5 March 2013 15:39, Andreas Mueller <[email protected]> wrote:
> On 03/05/2013 03:18 PM, Nelle Varoquaux wrote:
> > Hi everyone,
> >
> > I'm actually not convinced about the new layout (sorry Andy :( ). I
> > should also say, I'm not convinced about panda's website.
> >
> > The menu is, I think, quite confusing. Overall, I think there are two
> > many links which may refer to the same thing: the difference between
> > "installation", "getting started", "user guide" and "reference" is not
> > clear. Installation should probably be including in "Getting started",
> > or "Getting started" should be renamed to tutorial (but then, the
> > difference between tutorial and user guide is not clear).
> > Maybe we could have something like:
> > Home Download Documentation Gallery
> > Download would be a "real" download page.
> >
> > Documentation would have a "Installation", "Tutorial", "User guide",
> > "API reference" and "Contribute". (I would in fact merge Tutorial and
> > User guide together, as topics presented in the tutorial are in the
> > user guide too)/
> >
> I am not entirely sure I understand you criticism. The menu items
> correspond to different sections of the documentation,
> that already exist. Basically what I did is take out sections and made
> them menu items.
>
Maybe that is the problem the core problem. The documentation has not been
written to be without sections: before, the user guide was divided into
three parts:
1. Installation
2. Tutorials: an overview of the scikit
3. Unsupervised learning
4. Etc.
I don't think the new layout makes sense, maybe because it was not written
to be in a flat layout like it is right now.
> For "installation" vs "getting started": I can rename "getting started"
> to "tutorial" (the current name) or "quick start".
> I don't really see how a confusion could arise if you see "installation"
> next to "getting started". In which case would you not know where to look?
> Btw, I took "tutorial" out of "user guide", "installation" was already
> there (and called "download").
>
> For "Download": the file is called "Installation". The headline is
> "Installation". What it describes is how to install. I'm not sure why it
> is called "Download".
> If you had "download" there and "installation" in the docs, what would
> be on the "download" page?
>
Download links. If there is a "Getting started" link, installation should
be part of it. Else "Getting started" should be renamed or removed.
> If you claim that the distinction between installation, tutorial and
> user guide is unclear, then this is a problem with the organization of
> the documentation, not the website.
>
By changing the menu, you also changed the organization of the
documentation. I don't think changing the organization of the documentation
can be done without a large amount of work on the documentation itself.
> Basically inclusion of the tutorial created some doubling of
> information, that I also find quite confusing.
> How would you solve this issue, then?
I personnally would get rid of it, but ogrisel made a point. If we do have
a doubling of the information as right now, then it should be ordered
properly, which goes against the proposed changes.
I am not against a top-level menu with "Home Installation
> Documentation Gallery".
> But then "Documentation" should not be a huge flat list, but something
> where I can actually find things.
> Landing on a page with >100 links shown to me basically turns me away
> from the docs instantly.
>
This is where we don't agree. a page with more than 100 links allows me to
do a ctr+s on a page. Having less links means going through a more
intelligent search engine.
If it is just a matter of having less links on the page, an easy fix would
be to not display sub titles, and hence only have in the User Guide:
1. Installing the scikit
2. Tutorials
3. Supervised Learning
4. Unsupervised Learning
5. etc
So how would you structure the documentation? a menu on the side? What
> would be on the main "Documentation" page?
>
> > I also think the google search widget is quite important (thought I've
> > never used it)
> I prever discoverability over searchability. We can also put this
> somewhere else. I have never used it and there was a bug report saying
> it is not really useful.
> Also, you can just use google. The removal was not necessary meant to be
> permanent, though.
>
True.
Overall, I would like to stress that UI issues are really really hard to
solve, and it is very hard to have something that matches everyone needs. I
would be quite curious to see exactly the proportion of people who
complained about the architecture of the website, and how they use the
documentation. It is very likely that the changes we make for them will
have a negative impact on other types of users.
>
>
>
> ------------------------------------------------------------------------------
> Everyone hates slow websites. So do we.
> Make your web apps faster with AppDynamics
> Download AppDynamics Lite for free today:
> http://p.sf.net/sfu/appdyn_d2d_feb
> _______________________________________________
> Scikit-learn-general mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/scikit-learn-general
>
------------------------------------------------------------------------------
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics
Download AppDynamics Lite for free today:
http://p.sf.net/sfu/appdyn_d2d_feb
_______________________________________________
Scikit-learn-general mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/scikit-learn-general
