Jump to page: 1 2
Thread overview
Documentation Layout
Mar 28, 2012
James Miller
Mar 28, 2012
Adam D. Ruppe
Mar 28, 2012
Nathan M. Swan
Mar 28, 2012
foobar
Mar 28, 2012
Adam D. Ruppe
Mar 29, 2012
foobar
Mar 29, 2012
Nathan M. Swan
Mar 29, 2012
James Miller
Mar 29, 2012
foobar
Mar 29, 2012
Jacob Carlborg
Mar 29, 2012
Ary Manzana
Mar 29, 2012
H. S. Teoh
Mar 29, 2012
F i L
Mar 30, 2012
Marco Leise
Mar 30, 2012
Andrej Mitrovic
Mar 28, 2012
Ary Manzana
Mar 28, 2012
Jacob Carlborg
Mar 29, 2012
Jakob Ovrum
Mar 29, 2012
James Miller
Mar 29, 2012
Jakob Ovrum
March 28, 2012
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
March 28, 2012
On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote:
> 1. The "Jump To" index.

I did a little program called improveddoc that builds nicer
tables:

http://arsdnet.net/d-web-site/improveddoc.d

makes:

http://arsdnet.net/d-web-site/std_stdio.html


It does post-processing on the dom to build it.



We talked a while ago about integrating it into the
website build process, but I haven't gotten around
to figuring that out yet.

> 2. No ordering + unobvious separation of elements

I believe it is in the same order as the original source
code.

> 3. No search

Another thing I started but never finished is

http://dpldocs.info/

You can jump to a thing with:

http://dpldocs.info/std.stdio.file

or search:

http://dpldocs.info/file



the rest of your post is tl;dr, I'll look at it
later though.



The problem with my doc stuff is just finding the
time to finish off the integration. The basics
work pretty well now as you can see at the
links above.

March 28, 2012
On Wednesday, 28 March 2012 at 14:47:53 UTC, Adam D. Ruppe wrote:
> On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote:
>> 1. The "Jump To" index.
>
> I did a little program called improveddoc that builds nicer
> tables:
>
> http://arsdnet.net/d-web-site/improveddoc.d
>
> makes:
>
> http://arsdnet.net/d-web-site/std_stdio.html
>
>
> It does post-processing on the dom to build it.
>

That's pretty cool! I especially like the categories idea; it reminds me of Apple's documentation for Cocoa. It really helps you when you are thinking "I need a function which does...".

NMS
March 28, 2012
On 3/28/12 2:20 PM, James Miller wrote:
> Ok, so I'm going to say this: I like the Java documentation. There, I
> said it.

I like it too.

http://downloads.dsource.org/projects/descent/ddoc/phobos/
http://downloads.dsource.org/projects/descent/ddoc/tango/

And cross-references are not hard at all. The compiler has everything it needs to know them (it can compile your code, which is way more complex! :-P)

Back them when I presented that format (which could be improved, it's still hard to find something on the right pane) there wasn't a lot of interest for it. I think documentation look & feel is paramount.
March 28, 2012
On 2012-03-28 19:34, Ary Manzana wrote:
> On 3/28/12 2:20 PM, James Miller wrote:
>> Ok, so I'm going to say this: I like the Java documentation. There, I
>> said it.
>
> I like it too.
>
> http://downloads.dsource.org/projects/descent/ddoc/phobos/
> http://downloads.dsource.org/projects/descent/ddoc/tango/
>
> And cross-references are not hard at all. The compiler has everything it
> needs to know them (it can compile your code, which is way more complex!
> :-P)
>
> Back them when I presented that format (which could be improved, it's
> still hard to find something on the right pane) there wasn't a lot of
> interest for it. I think documentation look & feel is paramount.

I think the documentation generated by descent is great, it just need some styling :)

-- 
/Jacob Carlborg
March 28, 2012
On Wednesday, 28 March 2012 at 16:40:19 UTC, Nathan M. Swan wrote:
> On Wednesday, 28 March 2012 at 14:47:53 UTC, Adam D. Ruppe wrote:
>> On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote:
>>> 1. The "Jump To" index.
>>
>> I did a little program called improveddoc that builds nicer
>> tables:
>>
>> http://arsdnet.net/d-web-site/improveddoc.d
>>
>> makes:
>>
>> http://arsdnet.net/d-web-site/std_stdio.html
>>
>>
>> It does post-processing on the dom to build it.
>>
>
> That's pretty cool! I especially like the categories idea; it reminds me of Apple's documentation for Cocoa. It really helps you when you are thinking "I need a function which does...".
>
> NMS

Categories - worst idea ever.

What's better:
int a; // this is size
OR
int size;

Same thing applies here - code MUST be self documenting as much as possible.
D has an advanced module system yet people insist on treating D as if all we have are #includes. When that's coming from the developers of the standard library that looks like a huge warning sign to me.

While I applaud Adam's efforts I don't think that what we need is a complex multistage documentation system.

The recent posts about Rust peaked my curiosity and I picked at their docs. I was thoroughly impressed by the improvement they made since the last time I looked. The previous time (long ago) I quickly dismissed it but as their developer said himself it really shows that they eat their own dog food and the polish is very apparent.

The only think that annoyed me was the ridiculous abbreviation mess - looks like something a teenager on twitter would use. There's really no good reason to shorten return to "ret" and mutable to "mut". in fact, their code shows they started with "mutable" and then did a search/replace to shorten it. ?!?

March 28, 2012
On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:
> Categories - worst idea ever.

I was just trying to copy what std.algorithm does,
which is ok by me.

Though, my implementation allows multiple categories;
it is more of a tagging system (which is how my search
program works too, it puts common alias in as tags).
March 29, 2012
On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:
> Categories - worst idea ever.
>
> What's better:
> int a; // this is size
> OR
> int size;
>
> Same thing applies here - code MUST be self documenting as much as possible.

But categories are still useful, e.g., when you want a function in std.algorithm that looks for a specific element. It could be "search" or "find" or "firstElemSatisfyingCondition", and even though those are all self documenting, it would be a pain to look through the list of functions in alphabetical order. The use of categories narrows your search for the function down 20%.

NMS
March 29, 2012
On 29 March 2012 13:58, Nathan M. Swan <nathanmswan@gmail.com> wrote:
> On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:
>>
>> Categories - worst idea ever.
>>
>> What's better:
>> int a; // this is size
>> OR
>> int size;
>>
>> Same thing applies here - code MUST be self documenting as much as possible.
>
>
> But categories are still useful, e.g., when you want a function in std.algorithm that looks for a specific element. It could be "search" or "find" or "firstElemSatisfyingCondition", and even though those are all self documenting, it would be a pain to look through the list of functions in alphabetical order. The use of categories narrows your search for the function down 20%.
>
> NMS

Exactly my point. There is a line between "code must be self documenting" and "I need to read the code to understand what this does". Self documenting code is more about removing the cognitive stress of reading code. Actual documentation needs the whys and wherefores about everything.

std.string is a brilliant example, with a list of 68 functions at the top, and a total of 89 anchors (presumably just overloads), there is no easy way to quickly find a function for a purpose. You have indexOf - a searching function - next to insert - a manipulation function - next to isNumeric - a property testing function. Each of those functions are "self-documenting" but that doesn't mean they wouldn't benefit from categorization.

--
James Miller
March 29, 2012
On Thu, Mar 29, 2012 at 02:52:17PM +1300, James Miller wrote: [...]
> Exactly my point. There is a line between "code must be self documenting" and "I need to read the code to understand what this does". Self documenting code is more about removing the cognitive stress of reading code. Actual documentation needs the whys and wherefores about everything.

I would argue code comments should do the same.

This reminds me of when I was working as a teaching assistant in college. In class, the lecturer drilled it into the students that they need to comment their code, the more comments the better. So some students handed in code that looked like this:

	// Define a function
	int myfunction(int y) {
		// Loop from 1 to 10
		for (int i=0; i < 10; i++) {
			int x;		// declare a variable
			x = i;		// set x to 0

			// If condition is satisfied
			if (x*2 + y*3 - 7 < 9) {
				y--;	// decrement y
			}
		}

		// Return result
		return y*3 - x;
	}

Next class, the lecturer had to tell them that comments are not for restating what's already obvious from the code; they're intended to explain what *isn't* obvious, like what's the purpose of the function, what's the meaning behind the if-condition, etc..

I had my laugh then, but now I'm working in the industry and sometimes I see code like this:

	int somePoorlyNamedFunction(int y) {
		int x = 123;

		if (y*7 - 4*x + 9 < 16) {
			// Fix bug of wrong result
			return 19-x;
		}
		return 17-y;
	}

and I start wondering where people bought their diplomas from...


> std.string is a brilliant example, with a list of 68 functions at the top, and a total of 89 anchors (presumably just overloads), there is no easy way to quickly find a function for a purpose. You have indexOf - a searching function - next to insert - a manipulation function - next to isNumeric - a property testing function. Each of those functions are "self-documenting" but that doesn't mean they wouldn't benefit from categorization.
[...]

Yikes!! I think my next doc-related pull request may very well have to be std.string... :-/


T

-- 
"No, John.  I want formats that are actually useful, rather than over-featured megaliths that address all questions by piling on ridiculous internal links in forms which are hideously over-complex." -- Simon St. Laurent on xml-dev
« First   ‹ Prev
1 2