On 03/05/2013 04:04 PM, Nelle Varoquaux wrote:
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.
I don't see how I made the documentation flat.
I divided it further.
Also, the documentation was not written in this way. There was a
documentation, then we merged a completely separate tutorial.
The tutorial was not meant to be part of the user guide.
Download links. If there is a "Getting started" link, installation
should be part of it. Else "Getting started" should be renamed or
removed.
Do we really start arguing about names? that was a mock-up.
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.
I think the organization was horrible and hoped to improve it.
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 think my change makes it clear that these are separate things and how
they are to be consumed, while I found it very confusing before.
No-one will read the tutorial from beginning to end and then the user
guide from beginning to end. I don't think this is how the user guide is
used.
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.
I think this basically says: "I gave up on UI"
I have not managed yet to remember the search terms for all the things I
like to look up as most are mentioned multiple times.
I'll upload a somewhat renewed version soon. I challenge you to stop the
times you need to find something in the new organization and in the old
and see which is faster.
I tried to improve that by separating user guide and tutorials, and not
append the references to the user guide (which I found vastly confusing).
That makes searching a lot easier imho.
Having less links means going through a more intelligent search engine.
No, less links should mean you instantly know where to click.
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
We could do that. Actually I'm adding the java script for collapsing the
toc tree in right now.
The problem with that is that this generates a larger click distance
between the stuff behind the links.
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.
I can gladly give you access to the 400+ comments on the survey ;)
I can not imagine a case where flattening the interface would have a
negative impact on the users.
Ok, you and Gael disagree because you like to text search for things. I
think I am using the user guide
as least as often, and I find it horribly complicated to find any
section - this is from the standpoint of something
who knows quite well what is in the library.
For new uses, I imagine the problem to be much more severe - you don't
know what is in the library and you don't know what you are looking for
precisely.
------------------------------------------------------------------------------
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
Scikit-learn-general@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/scikit-learn-general
