View mode: basic / threaded / horizontal-split · Log in · Help
March 29, 2012
Re: Documentation Layout
H. S. Teoh wrote:
> and I start wondering where people bought their diplomas from...

Walmarts usually got the best deals.
March 29, 2012
Re: Documentation Layout
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?
March 29, 2012
Re: Documentation Layout
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...

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

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

--
James Miller
March 29, 2012
Re: Documentation Layout
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.
March 29, 2012
Re: Documentation Layout
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.
March 29, 2012
Re: Documentation Layout
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?
March 29, 2012
Re: Documentation Layout
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
March 29, 2012
Re: Documentation Layout
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?
March 30, 2012
Re: Documentation Layout
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
March 30, 2012
Re: Documentation Layout
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.
Next ›   Last »
1 2
Top | Discussion index | About this forum | D home