Documentation Layout

[foobar]

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?