@h3rald:
> problem in an absolute sense
Is there such a thing? ;)
> I don't think the average user of the language needs to know about
> implementation details and have in-depth discussions about performance and
> why things work in a certain way.
I don't think it's wise to decide what people need to know (it's not the same
as prioritizing less/more important info, though). What I think you meant is
probably a matter of presentation: clearly separate different blocks of
information so people seeking some specifics don't need to filter irrelevant
stuff. Secondly, _the average user_ in a literal sense doesn't read the headers
at all, but uses scrolling or Ctrl-F.
> you are right in saying that there's something missing from the current docs,
> but I would argue that the docs are not the right place for it: a specialized
> blog or a different document would.
I agree that language/library docs can't and shouldn't replace specialized
articles, however, I don't think it's necessary to maintain strict airtight
separation. Docs can have _a bit_ more tutorial-like content and more _gentle_
guidance, and if a user finds it's not enough then there are more detailed
articles/blog-posts/official tutorials/books/etc.
> Off topic: the message editor on this forum behaves quite oddly. When I
> expand the textarea and then lose tab focus, it jumps back to its previous
> size.
This drives me nuts all the time.
@xigoi:
> I don't think a standard library documentation should have a Data Structures
> Fundamentals tutorial,
No one made this argument. In fact, @shirleyquirk first mentioned this in his
post as a reply, but at least I'm not advocating for this, just look at the OP.
However, there's nothing wrong with have a line or two of the basics as a
refresher. At least they aren't going to become obsolete anytime soon.
@Araq:
> How do you know it's not wasted effort.
**No one** will write it unless they have anything better to do.
> And now you can say "yes, but good documentation is essential!", but what we
> have is already "good" \-- not "great" but then no matter how great our
> documentation is it's always very easy to blame the documentation for one's
> own shortcomings or lack of "motivation".
C'mon, I understand it's easy to interpret this thread as an attack, but I
really just reacted to more than a few comments from other users and wanted to
address this particular topic with some ideas. Whenever I have a critique I
always give at lease a hint at a possible solution. No one's blaming anyone.
You have all the rights to just ignore the points in this thread if you think
they are irrelevant or unimportant or a time waste.
Again, if you look at the OP, the only thing that could be interpreted as a
demand is: A central place where one could start working on the docs with:
Here's our general docs guide: https://foo
Here's the minimal checklist which is mandatory to follow for the docs to
be accepted: https://bar
Here's a bunch of GH doc tags you can follow: K, L, M
We're working on X, Y, Z, if you want to help with the docs report to their
authors A, B, C.
We need tutorials on F, G, H.
There's also a big post on topic Q coming, help us expand and proof-read.
Run
