Documentation Layout

[James Miller]

In another thread
(http://forum.dlang.org/thread/CAMfGmZsNX3GsOFVyUaCX79E4H8eTBXqDmUJtm41JSzRNtME=RQ@mail.gmail.com)
I raged about std.container's documentation, then Teoh pointed out
that a lot of Phobos documentation needs improving. While he was
talking about content, it got me thinking about the actual
presentation of Phobos's documentation. Now, I have an interest in UX
and I am a web developer my trade, so here's what I think it wrong
with general layout+design right now and what could be done to fix it.

1. The "Jump To" index.
This is the worst one for me, hence top of the list, its an inline
list of the classes, structs and functions on the page. Actually,
technically its a list of all the anchors on the page, with duplicate
names removed and then sorted (poorly) and outputted all in a row.
While this is manageable for say std.array, its ~4.5 lines on
std.string. Some modules have tables at the beginning that replace the
index, and this is better (std.algorithm for example) but can become
out of date, due to the fact that it is hand-maintained.

2. No ordering + unobvious separation of elements
Due to what I can only assume is the way DDoc generates code, there is
no obvious ordering to the page, you can have a class definition
followed by its methods followed by a few top-level functions then a
struct and its members. Combine this with the fact that all "things"
are styled the same, with indenting for members, you can easily get
lost scanning through a class when you suddenly find yourself at a
completely different class.

3. No search
Ok, there is a search, it is a small box, near the top, that searches
either: the entire site, the library reference or the news group. It
hands it off to Google and returns a Google search. This isn't very
good for user experience, ideally you wouldn't leave the site, it
would be internal and use the fact that you are searching
documentation to be a bit smarter about it.

4. Too static
As I have proved in other threads, I'm not exactly a fan of having
tons of Javascript all the time, but I think that some slightly better
interaction would be nice, I'll explain this more below.

5. Little-to-no cross referencing
Cross module references would be complicated and error-prone, so I
don't expect that. However, other than manually placed links, there
are no links in the actual documentation proper.


There's probably more, but these annoy me the most. Now unfortunately
I can't really deal with each point individually for a solution, so
I'll try to address all of them in the next section.

Ok, so I'm going to say this: I like the Java documentation. There, I
said it. Its clean, its functional, finding things is relatively easy,
sure it could be improved *cough*frames*cough*, but I like that trying
to find things isn't a mission. Anyway, the Java docs have some
particular layout features that I really like:

 * The whole screen is for documentation - This is important because
documentation is dense, and any chance to spread it out is great.
 * Drill down interface - Important for Java because of its tendency
to just produce more and more and more classes, but the idea is good
nonetheless.
 * Separation of elements - Again, there's a certain amount of
Java-specificness about this, since everything is in a class, and a
file can only contain one public class, but it gives a summary of the
class at the beginning, breaking it down into methods, methods
inherited, fields and constructors before going onto detail after
that.

While I do not advocate direct copying of the Java style, the ideas
are good. I think that a generated summary table at the beginning
would be better, probably have a very top-level one that has 4
separate lists: Classes, Structs, Functions and Templates, containing
all the module-level declarations in that file. From there, each
Top-level declaration is clearly separated from the others, with
Class/struct summaries if appropriate, and they are grouped together
according to type, and in the order that is presented in the list near
the top. This solves three of the problems with the list at the top:
easy scanning - a table of categorized data is easier to read than a
simple list; ordering - currently the list is ordered in alphabetical
order, but the contents is not, meaning that there is a disconnect
between the two presentations of the content, and that can get
annoying and finally, name duplication - if only top-level
declarations are used, then you can have all the names in the list,
since you won't have things like opIndex in the list, unless it is
actually a top-level function. The separation of the top-level
elements (and the inner elements in a class/struct) needs to be done
at both ends, you can't signal the end of one item by the beginning of
another, since that conflicts with the idea of nested items, just
indentation isn't enough to visually indicate ownership, boxes are
good, boxes contain things. This isn't code, its presentation.

However, all this extra information adds a new problem: filtering. If
you have a lot of code in one file, then trying to reduce the noise of
things you don't want to deal with is necessary. So we need
collapsible sections, they don't have to be fancy, and they can be an
add-on, so no javascript simply means no collapsing. This means that I
can look at something, collapse it to indicate that it isn't relevant,
then move on. When flicking around the page, it's easier to see what I
have already looked at in this case. There are a multitude of other UX
enhancements you can make, but this one is simple and efficient.

Expanding on point 3, basically, if a search exactly matches a
function, then you should get taken straight to the documentation for
that function, PHP is a brilliant example for that, since that is
exactly what it does. It assumes you are looking for a function/class,
and if it can't find it, gives you close-match suggestions at the top
and then general results near the bottom. This is incredibly
efficient, since sometimes I know the name of the function and just
want to see argument order, or I might have an idea of the function I
want, but can't remember the exact name, PHP knows better what
functions it provides than Google, so it doesn't use Google. We could
also do the Wikipedia trick of "We couldn't find a function/class by
that name, did you mean <list of options>? Otherwise search the entire
site" and that last bit can still be Google.

Point 5 is pretty self explanatory, when trying to figure out how to
use a module, you might need to look at several different Types and
functions, all related, but they don't get linked to each other much,
you just have to guess.

Other things that would be awesome would be having a separate
"Concepts" section, like the articles, but specifically for concepts,
especially if they are D related. Ideally each module would have its
own concepts page, but that isn't always reasonable or feasible. Being
able to manually assign importance to certain items in code, for
example in std.random, the first item is the struct
LinearCongruentialEngine, but most people probably just want rndGen +
usage or uniform + usage, they are far more useful in most cases and
should be nearer the top. On a related note, providing alternative
"usage" declarations for things would be useful, especially complex
templated functions where all the templated arguments are inferred
most of the time, even if this one of the javascript-enabled features,
so by default the standard declaration could be shown, then if
javascript is enabled, they get replaced with alternative declarations
and you get a button to switch. Similarly, skipping or hiding
unnecessary functions and classes that are only useful for advanced
usage (like the RNG engines, most people are fine with MT19937) would
be good for newer users, since often they lower the signal-to-noise
ratio for all users, and more so for newbies.

Some of these things are things that need to be changed, some are just
fancy wishlist-type items. Mostly, better discoverability is the top
priority overall, so newer members (which may include me, depending on
who you ask) don't get frustrated trying to figure out how to do
otherwise simple things.

I understand that a lot of this due to the limitations of DDoc, so
either that needs improving, or we need to make a new tool, even if it
is just for Phobos, or other large projects. The standard library is
supposed to be a showcase of some of our best work, but right now the
case is old and busted, we need to make it the new hotness.

--
James Miller