Documentation Layout

[Marco Leise]

Am Wed, 28 Mar 2012 18:40:17 +0200
schrieb "Nathan M. Swan" <nathanmswan at 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