www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documentation Layout

reply James Miller <james aatch.net> writes:
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
Mar 27 2012
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
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.
Mar 28 2012
parent reply "Nathan M. Swan" <nathanmswan gmail.com> writes:
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
Mar 28 2012
next sibling parent reply "foobar" <foo bar.com> writes:
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. ?!?
Mar 28 2012
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
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).
Mar 28 2012
parent "foobar" <foo bar.com> writes:
On Wednesday, 28 March 2012 at 23:30:32 UTC, Adam D. Ruppe wrote:

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


As I said - I do appreciate your efforts :)
I just think the problem is deeper than just the documentation 
system though I do agree DDoc needs a lot more work.
I just feel that this specific issue is 98% about incorrect 
organization of code and only about 2% of improving DDoc 
presentation and usability.

At my previous work, the code base was so huge that the company's 
core library was designed to have a flat structure of files, eg 
component_file.cpp instead of component/file.cpp because someone 
decided this is the proper solution to reduce compilation times. 
apparently changing dirs increases compilation time.
This is butt ugly and vary inconvenient also given the moronic 
abbreviations used to shorten the file names.

I'm wondering at what point do we realize the problem is with the 
system and not us - clearly the long compilation times are due to 
C++ compilation model and not my organization of modules.
I can't influence the design of C++ but I hoped newer languages 
will learn from past mistakes. after all - should we serve the 
machine or should it serve us?
Mar 29 2012
prev sibling parent reply "Nathan M. Swan" <nathanmswan gmail.com> writes:
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
Mar 28 2012
next sibling parent reply James Miller <james aatch.net> writes:
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
Mar 28 2012
parent reply "foobar" <foo bar.com> writes:
On Thursday, 29 March 2012 at 01:52:28 UTC, James Miller wrote:

 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


Have you considered that perhaps the granularity of Phobos 
modules is too coarse? Perhaps the core issue is too many 
functions are placed in one single file without more 
consideration of their relation and organization?

Regarding the documentation system itself - it should provide as 
much automation as possible. For instance, it should be able to 
group overloads together, it should be able to group kinds 
together - types, free functions, enums, etc. it should be able 
to group together various parts of a compound type (by 
protection, by kind: constructors, properties, operators, etc. )

Given the above *and* proper organization of code - which is 
*not* the case today - an *optional* tagging system could add 
some small benefit if it's automatic. E.g add a TAG macro.

Relying on documentation before exhausting the above is IMHO 
wrong.

As others said, the documentation and code comments should 
reflect what the code itself cannot express - what is the higher 
goal we want to achieve, which  specific implementation tradeoffs 
were taken and why, etc.

breaking algorithm.d into manually maintained documentation 
"categories" clearly misses the above points.
Mar 29 2012
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-03-29 11:24, foobar wrote:


 Have you considered that perhaps the granularity of Phobos modules is
 too coarse? Perhaps the core issue is too many functions are placed in
 one single file without more consideration of their relation and
 organization?

 Regarding the documentation system itself - it should provide as much
 automation as possible. For instance, it should be able to group
 overloads together, it should be able to group kinds together - types,
 free functions, enums, etc. it should be able to group together various
 parts of a compound type (by protection, by kind: constructors,
 properties, operators, etc. )

 Given the above *and* proper organization of code - which is *not* the
 case today - an *optional* tagging system could add some small benefit
 if it's automatic. E.g add a TAG macro.

 Relying on documentation before exhausting the above is IMHO wrong.

 As others said, the documentation and code comments should reflect what
 the code itself cannot express - what is the higher goal we want to
 achieve, which specific implementation tradeoffs were taken and why, etc.

 breaking algorithm.d into manually maintained documentation "categories"
 clearly misses the above points.


I completely agree.

-- 
/Jacob Carlborg
Mar 29 2012
prev sibling parent Ary Manzana <ary esperanto.org.ar> writes:
On 3/29/12 5:24 PM, foobar wrote:

 On Thursday, 29 March 2012 at 01:52:28 UTC, James Miller wrote:

 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:







 Have you considered that perhaps the granularity of Phobos modules is
 too coarse? Perhaps the core issue is too many functions are placed in
 one single file without more consideration of their relation and
 organization?


I think it's just fine. Not everything is in std.algorithm, and that's 
good. Because everything we write is an algorithm, right?

I mean, what can I expect to find in std.algorithm? Binary search? Index 
of? Levenshtein distance? Spanning tree? Minimum weight? TSP?
Mar 29 2012
prev sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
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
Mar 28 2012
parent "F i L" <witte2008 gmail.com> writes:
H. S. Teoh wrote:

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


Walmarts usually got the best deals.
Mar 28 2012
prev sibling parent reply Marco Leise <Marco.Leise gmx.de> writes:
Am Wed, 28 Mar 2012 18:40:17 +0200
schrieb "Nathan M. Swan" <nathanmswan gmail.com>:


 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


Unfortunately the function that reads a file in chunks is a _struct_ called
(lower case) chunks.
The function that returns the current time is a method of the class Clock.
Categories help us to divide and conquer the documentation, but it can still be
misleading at times. This is mostly due to the flexibility of the language,
that allows to use structs as functions (opCall), classes as namespaces (static
methods) as well as templates. On top of that there are concepts that are
spread out over several modules. Especially string handling which is in both
std.string and std.array. Other such cases can be found with
std.range/std.algorithm, I/O and numerics.
Seriously, I think the way modules are complementing one another make it a bad
approach in the long run to only document separate modules.

There have been a few attempts at making DDoc more digestible. My approach
would be:

1. List use cases:
  * What's the parameter order of function X?
  * Give me an overview over [string manipulation|range algorithms|...].
  * What is contained in/the purpose of module X?
  * more?
2. Find out what is required to support each use case
  * Proposed concepts section?
  * Wiki pages/links
  * External DDoc files to allow documenting outside the constraints of a
single module?
  * ...
3. Check back with what is already there and how to extend it

-- 
Marco
Mar 30 2012
parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 3/30/12, Marco Leise <Marco.Leise gmx.de> wrote:

 snip


Here's another mind-bender:

import std.typetuple;
Tuple!(int, int) x;  // bzzzzz

It's in std.typecons of all places. I would assume a tuple would be in
a module called typetuple, but no.
Mar 30 2012
prev sibling next sibling parent reply Ary Manzana <ary esperanto.org.ar> writes:
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.
Mar 28 2012
parent Jacob Carlborg <doob me.com> writes:
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
Mar 28 2012
prev sibling parent reply "Jakob Ovrum" <jakobovrum gmail.com> writes:
On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller 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.
 -snip-


There is a simple project called cuteDoc (name comes from the old 
candyDoc theme) which has a demo using the Phobos documentation:

     http://robik.github.com/phobos/

Project home page:

     https://github.com/robik/cuteDoc

It has some rudimentary JavaScript for a module list and a 
generated jump-to table. I would love to see the Phobos 
documentation on dlang.org do something similar; there's so much 
low-hanging fruit for D's documentation that I wish someone with 
some web savvy would pick up on. It's pretty baffling to think 
that some Phobos modules have *manually maintained* table 
headers, what the heck were people thinking? What happened to 
automation?
Mar 28 2012
parent reply James Miller <james aatch.net> writes:
On 29 March 2012 18:26, Jakob Ovrum <jakobovrum gmail.com> wrote:

 There is a simple project called cuteDoc (name comes from the old candyDo=


c

 theme) which has a demo using the Phobos documentation:

 =C2=A0 =C2=A0http://robik.github.com/phobos/

 Project home page:

 =C2=A0 =C2=A0https://github.com/robik/cuteDoc


It looks ok, still a little too cluttered for my liking. Also, serif
fonts on a web page...


 It has some rudimentary JavaScript for a module list and a generated jump=


-to

 table. I would love to see the Phobos documentation on dlang.org do
 something similar; there's so much low-hanging fruit for D's documentatio=


n

 that I wish someone with some web savvy would pick up on. It's pretty
 baffling to think that some Phobos modules have *manually maintained* tab=


le

 headers, what the heck were people thinking? What happened to automation?


I would, but I don't have the time. I've thought about it, but I work long =
days.

--
James Miller
Mar 28 2012
parent "Jakob Ovrum" <jakobovrum gmail.com> writes:
On Thursday, 29 March 2012 at 05:41:30 UTC, James Miller wrote:

 On 29 March 2012 18:26, Jakob Ovrum <jakobovrum gmail.com> 
 wrote:

 There is a simple project called cuteDoc (name comes from the 
 old candyDoc
 theme) which has a demo using the Phobos documentation:

    http://robik.github.com/phobos/

 Project home page:

    https://github.com/robik/cuteDoc


 It looks ok, still a little too cluttered for my liking. Also, 
 serif
 fonts on a web page...


I think the theme has a long way to go. There are a lot of weird 
choices of colour and such, and I think it has too many boxes. I 
think it would look better if the style was toned down a little.

It's merely an example of how little effort is required to make 
DDoc better. Issues with DDoc itself aside, the current state of 
dlang.org is hardly representative of DDoc's full potential, when 
it should be striving to be just that.
Mar 28 2012