On Wednesday, 18 March 2015 at 18:09:07 UTC, Walter Bright wrote:
On 3/18/2015 10:55 AM, Zach the Mystic wrote:
No responses yet -- not that I'm any less guilty than anyone
else. But maybe
this needs to be bumped up to a higher priority -- a hiatus on
internal
development for a couple weeks solely to bring documentation
up to a minimum.
Obviously clear guidelines like the ones you just posted are a
plus.
We have a great language, but represent it poorly in the
documentation. Every library entry also needs a pithy example
(or even any example at all), but I thought we could make
progress first by simply documenting what the return value is
supposed to be.
We also need to stop pulling new library additions that have
obviously inadequate documentation.
I'm just thinking in terms of psychology. I haven't seen anyone
disagree that the documentation is inadequate, so that's not even
disputed.
But why, therefore, is it so hard to get movement on it? I
suspect that it's because it is perceived as a chore, like
cleaning a barn. I don't want to go in that barn by myself. But
if I everyone's doing it, with the mutual understanding that it
needs to get done - and no one is exempt - then it doesn't feel
so bad.
At some point, it must be possible for documentation to get so
bad that *nothing* is more important. Otherwise, it may well
continue to flounder in destitute obscurity, never receiving the
attention it deserves.
