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.
