Mockup of my doc dream ideas

[Adam D. Ruppe via Digitalmars-d]

On Friday, 25 December 2015 at 17:00:05 UTC, default0 wrote:
> Aren't these usually called tutorials? Or am I misunderstanding 
> what you mean here?

Oh maybe, I've heard "tutorial" used in a lot of contexts and a 
lot of meanings though, so I wanted to be more specific.

> This is literally one of the things that bothers me most about 
> the documentation. Mostly when I try figure out how to do 
> something I use google.

Google does a really bad job on the D docs... and the D docs 
don't have enough anchors for it to pick up anyway. (Even if I 
want to manually share a link, there aren't links to most the 
ddoc sections! Aaargh!)

But the improved interlinking ideas will help with all of that, 
single pages or separate pages.

> templates and template constraints isn't always straightforward 
> if you aren't too familiar with the language and its idioms 
> (ie: if you're new to it and trying to learn).


Yeah, I think there's three general levels of users:

1) those who don't speak D-ese at all and need to learn the 
language. D-ese includes more than D itself, but also phobos 
idioms, general layout, etc.

These people really need higher level docs to make sense of it. 
Tutorials and conceptual overviews need to be written with these 
people in mind.

2) People who are conversational, but not fluent, in D-ese. They 
can basically get stuff done but don't know it all.

The function-level docs should be good enough for them, but it 
should translate some of the harder stuff to plain English. Don't 
ask them to read a constraint mess, just say it in words and in 
examples.

This is the target audience of the stdlib inline docs IMO. They 
know how to get there, but then need some assistance bringing it 
back home.

3) People who are fluent in D-ese. The docs aren't terribly 
important to them except to quickly refresh themselves. They are 
fully capable of reading the source, but like the docs for a 
quick outline.

The actual content isn't really important to these folks, they 
just want a convenient index.

> Plus I'm probably biased since I'm coming from C# and thus am 
> heavily used to the MSDN docs.

Yeah, MSDN is great, I think it will be my main model.