Documentation Layout

Brad Anderson eco at gnuk.net
Wed Mar 28 00:00:19 PDT 2012


On Wed, Mar 28, 2012 at 12:20 AM, James Miller <james at aatch.net> wrote:

> 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.
>
>
Yeah, I'm not a fan of the Jump To links.  They are often unwieldy and not
in any easily discernible order so they are often just clutter. I was
toying with the idea of making it only show top level structs, classes, etc
and then possibly having yet another Jump To section above each
struct/class with nested symbols.  I haven't looked into how easy this
would be to do yet.


> 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.
>
>
Agreed.  I'm not sure what can be done about the way ddoc orders things
though.  As far as I know it's just in the order it appears in the source.
I'm not sure how you'd even go about specifying a different ordering from
source order (even ignoring ddoc, just speaking of documentation generators
in general).


> 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.
>
>
I've been trying to generate parsable ddoc output for use in an
autocomplete for the search box (symbol names + short documentation
excerpts for context).  I had some luck but couldn't strip it down to the
bare minimum information I wanted to extract so I got it in my head that I
should try adding documentation to dmd's json output instead.  I haven't
attempted this yet.  I think the search is very important.  Right now
someone basically has to tell you where which module certain
structs/classes are in std.typecons has a lot of useful stuff but nobody
would ever think to check there to find out where tuples or RefCounted are.
 Just yesterday I was very confused about why the documentation for
'recurrence' had gone missing but it turns out it's in std.range, not
std.algorithm.


> 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.
>
>
I think this just has to be done manually.

>
> 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.
>
>
I would welcome more order/structure.


> 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.
>
>
I dislike collapsible sections but that's just me.


> 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.
>
>
What I was envisioning would be just offering the autocomplete listing as
you type rather than a full blow results page.  Hitting enter without
highlighting an autocomplete would just do a regular search.


> 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.
>
>
I've written in the past about wanting a "Concepts" section myself so I
agree here.  I've had adding short little intro sections like some of the
better documented modules have to some of the underdocumented modules on my
todo list but haven't yet looked into it beyond having the idea.


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

Regards,
Brad Anderson
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20120328/b2d9eed3/attachment-0001.html>


More information about the Digitalmars-d mailing list