Re: [9front] The 9 Documentation Project

[Stanley Lieber <sl@stanleylieber.com>]

On July 27, 2020 4:01:18 PM EDT, ori@eigenstate.org wrote:
>> part of the problem for new users is that plan 9 assumes any user
>> understands the fundamentals of computing at a deeper level than even
>> "power users" of other systems.  this was already a stumbling block
>in
>> the 1990s, and it has only deepened as operating systems drag the
>user
>> experience farther and farther away from the underlying mechanisms.
>
>That's a part of it. But a part of it is that there's a lot
>of documentation that either sucks or doesn't exist. For
>example, I'm not aware of anything that documents the rather
>unique ways we handle scrolling, where how far up the window
>you are affects how quick the scrolling goes.
>
>NDB also seems like a constant source of confusion -- and
>while it largely makes sense when you get it, I don't think
>that the manpages lay it out very well.
>
>So, while I don't think we want to fix the assumption that
>you understand how your computer works, a combination of
>picking better defaults and documenting things better is
>something that *I* will appreciate, and I've been around
>9front for a while.

yes. i wasn't arguing that we don't need more and better documentation. we always do.

my experience with this struggle over the past ten years has been that nobody ever helps. everyone has good ideas, but nobody ever helps. see also: bug tracker.

perhaps ironically, the parts of the fqa that people complain about the most are the few parts held over from the old google code wiki.

i strongly support a public wiki.

sl