The 9 Documentation Project

The 9 Documentation Project

[sirjofri+ml-9front]

Hello all,

I thought about this some time and think we can do documentation better. Of course we have the very good fqa (which is 9front "only") and the official man pages as well as other documentation sources and guides. Most of these guides are distributed in various personal blogs and contribution to man pages and the fqa takes time (patch creation, review).

Since many of us users do happily provide information and guides as well as write ups I think we can create one active place for documentation that's too much for the fqa and the man pages as well as highly dynamic with changes everyday. (I want to mention the arch wiki as an example.)

My dream is something like a publicly available wiki system (wikifs?) with good structure where every nine user can contribute to without review. It would be interesting to have real authenticated accounts for write access, but that might be too much.

Here are some points I thought about and we can discuss:


- the documentation is publicly available, readable for everyone
- only plan 9 users can write (to prevent spamming)
- users need only plan 9 board tools to access the wiki (no extra software needed)
- discussion board for pages/page sections (no email needed)
- discussion chat for real-time discussions about the wiki (like hubchat/ants, documentation related content preferred)
- multi-distribution support. Most users use 9front, but it's worth mentioning differences between systems. This should happen in a structured manner.
- documentation download: users can download pages for offline reading. Maybe typeset and/or different formats.
- having authenticated user access would be interesting to see how a public auth server can work. This is not necessary, but I think it's worth it (and it can be used for other future fileserver projects)

These are just some ideas we can discuss. Keep in mind I don't want to create another distributed source for documentation, but a central "wiki" you can use to share information with other users, so we can collect all undocumented knowledge in one place.

I know there are other wiki places, for example:

9gridchan wiki, with focus on ANTS tools and the public grid project. I don't think people go there for general plan 9 advise.

9p.io wiki, which is more like an archive for the original plan 9 wiki. I don't know who owns this and how actively it's used.

Also this is _not_ meant as a replacement for the man pages and the fqa. The project should also encourage users (and developers) to contribute to the man pages. There are programs that don't even have a man page, as well as missing important information.

With this I want to open the discussion, feel free to share your ideas and comments. I hope we can make some good documentation together.

sirjofri

Re: [9front] The 9 Documentation Project

[hiro]

i wish i knew a good answer for all this, but good to start talking about this.
about 9p.io wiki: that is from wikifs(4)

Re: [9front] The 9 Documentation Project

[Amavect]

There is a wiki here:
https://code.9front.org/wiki/FrontPage
It should probably be replaced by something accessible from 9front, though.

Thanks,
Amavect

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

http://wiki.9front.org/

no one used it, for years. the current state of 9front documentation reflects the current state of 9front documentation activity.

sl

Re: [9front] The 9 Documentation Project

[ori]

> I thought about this some time and think we can do
> documentation better.  Of course we have the very good fqa
> (which is 9front "only") and the official man pages as well as
> other documentation sources and guides.  Most of these guides
> are distributed in various personal blogs and contribution to
> man pages and the fqa takes time (patch creation, review).

This is the important part.  Which blog posts do you
think are worth merging into the FQA?

Which ones are too deep for the FQA, but would make
good pages for the wiki, or /sys/doc, or whatever else?

What components of the system have no adequate docs?

The content is the important part, and we can improve
the infrastructure as we go.

> - the documentation is publicly available, readable
>   for everyone
> - only plan 9 users can write (to prevent spamming)
> - users need only plan 9 board tools to access the
>   wiki (no extra software needed)

For now, I don't particularly care what we decide
on. Wikifs is fine, but so is the current wiki, a
git or hg repo with text files, or scratching it
on the walls.

> - discussion board for pages/page sections (no email needed)
> - discussion chat for real-time discussions about the wiki
>   (like hubchat/ants, documentation related content preferred)

I think pointing people to IRC or gridchat would be
sufficient here. We can fragment things after the
volume gets higher.

> - multi-distribution support. Most users use 9front, but
> it's worth mentioning differences between systems. This
> should happen in a structured manner.

That's more work, and we're already short on hands.
Maybe a single 'some differences from labs' document
would be nice, but I don't want to dig through labs
code/docs to see what changed every time I update
something.

> - documentation download: users can download pages for offline
> reading. Maybe typeset and/or different formats.

If we do this well, I think it'd be worth including a
snapshot in the distribution.

> - having authenticated user access would be interesting to see
>   how a public auth server can work. This is not necessary, but
>   I think it's worth it (and it can be used for other future
>   fileserver projects)

It would be.

Re: [9front] The 9 Documentation Project

[William Gunnells]

Wonderful Idea. When I don’t understand something in FQA I end up at 9p.io. I’m also tired of going back and forth from Openbsd to Plan9 just for a browser or some documentation. This may be ignorance on my part. It appears older documentation exists on the 9front install. It would be nice is FQA was installed in the doc section on a 9front install. Perhaps it doesn’t matter because after all it is a reflection of the manages. 

Mothra does handle browsing to 9p.io and 9front.org so that is nice. I’m really trying to make that jump and install it native. But i’m just not ready. 

If you read all of the documentation which appears to be a lot than some of the questions asked are supposed to become obvious. But honestly that is not where my brain is at. Too many years in BSD or Linux. Plan9 is simply very different and requires a very different mindset. At the end of the day when I have time to learn plan9 i’m already tired and making dumb mistakes. 

Mail was kind of a pain to setup for me. I made two elusive credentials and the "open /ipmas/asdf.asdf" and "upas/fs” much more difficult then it should have been. I made it more difficult and I recognize that. 

I feel like we need more documentation on how to use the system. Like a day to day thing. I recall watching a video of someone who made the port of plan9 to ARM for raspberryPi. I really got to see it in action and how one person would use
and work with this strangely wonderful OS. 

There is a link on 9p.io about Expanding your grid. 

https://9p.io/wiki/plan9/Expanding_your_Grid/index.html

I’m kind of stuck at Level 2 and champing at the bit to actually ‘srv’ files between different CPU/Auth’s. This Plan9 really makes certain tools like ssh and or other protocols a joke. Why are more people not using this. Well the learning curve is too fucking high i don’t believe it was a browser that halted this progress. It was the documentation. 

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

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.

sl

Re: [9front] The 9 Documentation Project

[William Gunnells]

Agreed. But it's more than that. Linux now makes you seriously lazy. Ubuntu wants to do everything for you. Uncomment file and ’service blah restart’ barely any research required. Overtime you forget because the expectations of what a stable service should do. Well maybe stable.

It’s the same with programming. I got stuck doing python for years because it was what the company required and wanted. So I gave in and did it. Then I switched company and ran into a situation where Python was not feasible. It was extremely slow for the task that I had to complete. I picked C# because they had already written a bunch of tools for what i needed. I felt like an idiot for a few days because I had no choice but to deal with bad practices I picked up such as duct typing, improper casting, static typing wow, and bytes on a stack! With python over time I didn’t care about the objects. The regret is huge. Its like starting over when you revert to a really programming language.

Companies today are pumping out bad code and sadly I made poor contributions to that code because of laziness.

> On Jul 27, 2020, at 10:29 AM, Stanley Lieber <sl@stanleylieber.com> 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.
> 
> sl

Re: [9front] The 9 Documentation Project

[ori]

> 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.

Re: [9front] The 9 Documentation Project

[Ethan Gardener]

ori wrote:
> 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.

NDB and auth. I'm a long-time user who *still* doesn't get it, and I don't think I'm the only one.

Re: [9front] The 9 Documentation Project

[Anthony Martin]

ori@eigenstate.org once said:
> 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.

 From rio(1):

  Mousing inside the scroll bar moves text: clicking button 1 with the
  mouse pointing inside the scroll bar brings the line at the top of
  the win- dow to the cursor's vertical location; button 3 takes the
  line at the cursor to the top of the window; button 2, treating the
  scroll bar as a ruler, jumps to the indicated portion of the stored
  text. Holding a button pressed in the scroll bar will cause the text
  to scroll continuously until the button is released.

Cheers,
  Anthony

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

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

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

On July 27, 2020 6:06:51 PM EDT, Anthony Martin <ality@pbrane.org> wrote:
>ori@eigenstate.org once said:
>> 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.
>
> From rio(1):
>
>  Mousing inside the scroll bar moves text: clicking button 1 with the
>  mouse pointing inside the scroll bar brings the line at the top of
>  the win- dow to the cursor's vertical location; button 3 takes the
>  line at the cursor to the top of the window; button 2, treating the
>  scroll bar as a ruler, jumps to the indicated portion of the stored
>  text. Holding a button pressed in the scroll bar will cause the text
>  to scroll continuously until the button is released.
>
>Cheers,
>  Anthony

I think ori is talking about scrollwheel behavior, which in any case, yes, behaves the same way as clicking inside the scrollbar.

sl

Re: [9front] The 9 Documentation Project

[Kurt H Maier]

On Mon, Jul 27, 2020 at 06:17:41PM -0400, Stanley Lieber wrote:
> 
> 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.
> 

Everybody always talks about the weather, but nobody does anything about
it.

I put up code.9front.org/wiki mostly so we can demonstrate that large
swaths of time go by with no changes, and the changes that show up are
generally from a handful of people.  I don't really like wikis as
documentation and/or knowledge bases because they only work when a
preponderance of users contribute.  I would much prefer thet see
specific sections of the FQA overhauled in a thoughtful manner, but I
sure do not have free time for that at the moment.

The problem with the current introductory garden path is that each piece
of advice reults in roadblocks to future pieces of advice, e.g. "set up
a terminal that can accept cpu connections, now set up these services on
another machine, now tear down step one and rebuild it in step two's
image" etc.  It works for "zero to running" but it sucks as a
pedagogical approach, as not all learners do well with the "draw the
rest of the fucking owl" approach.

Old electronics manuals (specifically, here thinking of Textronics
oscilloscope manuals) used to have a section entitled "Theory of
Operation" which went over at a high level what each component and/or
panel button did and why, culminating in an explanation of how they
worked together in common scenarios.  Such a document explaining what
these services (ndb, factotum, secstore, rpcu, etc) do without getting
distracted by administration instructions may be a valuable document.

"What does this tool do and when do I use it" is a fundamentally
different question than "how do I operate this tool" and I think mixing
them in the FQA may be doing a disservice to some segment of the
readership.  I personally prefer the mixed approach, but I'm not
everyone.  Yet.

khm

Re: [9front] The 9 Documentation Project

[ori]

> On July 27, 2020 6:06:51 PM EDT, Anthony Martin <ality@pbrane.org> wrote:
>>ori@eigenstate.org once said:
>>> 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.
>>
>> From rio(1):
>>
>>  Mousing inside the scroll bar moves text: clicking button 1 with the
>>  mouse pointing inside the scroll bar brings the line at the top of
>>  the win- dow to the cursor's vertical location; button 3 takes the
>>  line at the cursor to the top of the window; button 2, treating the
>>  scroll bar as a ruler, jumps to the indicated portion of the stored
>>  text. Holding a button pressed in the scroll bar will cause the text
>>  to scroll continuously until the button is released.
>>
>>Cheers,
>>  Anthony
> 
> I think ori is talking about scrollwheel behavior, which in any case,
> yes, behaves the same way as clicking inside the scrollbar.

I was -- but I also had forgotten that this was in the rio manpage.

The reason I was thinking of this is because I made triple click
do something useful recently -- and made it work the same across
sam, rio, acme, and vt, and was thinking it'd be nice to have a
single document that described these conventions.

Re: [9front] The 9 Documentation Project

[ori]

> Old electronics manuals (specifically, here thinking of Textronics
> oscilloscope manuals) used to have a section entitled "Theory of
> Operation" which went over at a high level what each component and/or
> panel button did and why, culminating in an explanation of how they
> worked together in common scenarios.  Such a document explaining what
> these services (ndb, factotum, secstore, rpcu, etc) do without getting
> distracted by administration instructions may be a valuable document.

Yes. that's the kind of thing I was wishing we had. Something like
/sys/doc/comp.ps. I think the preferred way of managing docs for me
would be /sys/doc, mirrored to the web -- but I don't care enough to
argue over that: if a wiki gets people to write, I'd be happy with
that.

I'd started sketching out something for ndb, though who knows when
I'll have time to get it done.

Re: [9front] The 9 Documentation Project

[sirjofri+ml-9front]

Hello,

lots of input by lots of people. I didn't expect this.

Seems like there are some points to consider when doing this kind of project:

A wiki is always faster to edit. Changes don't need a review and can be applied automatically.

There's a lack of fundamental information and the high level concept: I see it differently. There's lots of material in /sys/doc about high level stuff, but it's too high level to work with (or too low level so users don't need it).

For example, factotum. Reading through like 3 papers about auth and factotum you can understand what factotum is and what a role it plays, but you still have no idea how/when to use it. You know something about secrets and that there is a secstore, but then you are confused by terms like keyfs, auth server, cpu server etc. Because plan 9 is a distributed system it's not easy to describe all that correctly and understandable.

Re. Power users: I consider plan 9 users as power users for now. You need to learn it over time, bang your head on the table if you don't get it and then be happy about trying it again. It can be very frustrating, but still I think we can do better.

By the way, this has its good side: Users are encouraged to search for direct contact with the developers. I never talked to a linux dev, for example.

Re. /sys/doc: I think it's a good idea to have a "fundamentals" section in the wiki that is mirrored into /sys/doc on a regular basis (eg monthly) or the distributed wiki (/sys/lib/wiki, I think?). This way fundamental things are included and the system stays small.

Re. Wiki system: wikifs would be easiest and could be implemented without further development. There are features I miss (and also features other users miss), like nested links and duplicate page names. Also page renaming is impossible. Wikifs is old, but we could also use it as is and improve it with necessary features. I'd like compatibility with the original wikifs, but at some point that's impossible. We could also think about using a completeley different solution.

Re. unnecessary features like chat etc: yes, we can still refer to 9gridchan and other platforms. There's no reason to establish a new communication platform in this small community.

Re. fqa: The fqa also has another important reason, in my opinion. It is a loving example of the culture and the humor (besides explaining things). I can imagine it's better to have one main author for the fqa, so it is one consistent document (book). The wiki will be an ever changing living document written and improved by many people.

These are my 5 cents.

sirjofri

Re: [9front] The 9 Documentation Project

[hiro]

> 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.

some ideas are no help and some help i gave was no good idea.
for me it has not been a struggle though.

even though our communication is very basic and non-organized, it
seems like a very relaxed, pleasantly experimental atmosphere and i
feel like i have enough space to envision the future, as opposed to
our dayjobs with only shitty uninformed code.

but that's just me, what about the 9front community? what do *we* want
out of this apart from a nice meditative shrine? what are the most
pressing issue?
obviously there can only be one valid goal: 9front world domination,
file servers for president. there has never been a bigger power vacuum
in the US before this clown as a president, and it's time we grab it
now.
for this we need to channel our strengths, and develop new strengths,
working together will benefit everybody.

for some it is hard to communicate efficiently, they have to become stronger.
some don't want to communicate, they have to become more passionate.

and some want to just play with the system and have some fun. they
have to carry on what they are doing, otherwise they should just go
outside and find something more fun that at least doesn't have
anything to do with sitting on a chair all day and waste their health
doing boring computershit.

but what if you decide to communicate, and collaborate, and want to
produce great code and great documentation for all of us?

generally people are most productive when writing stuff for
themselves. they shouldn't stop doing this.
just don't be sad it if isn't imported directly as is into mainline
9front. if their result is great, and if they are responsible and
collaborative they will want to either communicate the wisdom achieved
or even generalize their code into something that can be imported into
9front. only in the latter case we should need to actually *do*
anything (apart from just talk talk).

a lot of this is happening on IRC, which I sometimes follow closely.
when i think it's working well enough i'm obviously biased, as some
people reject IRC. for those what I think of as informal
drafts/proposals and ideas on irc is not visible in any other form or
document. there's often no mail, no website, no paper, no publication,
no pdf, nothing. I didn't feel a need for this to change, but
admittedly right now there's more noise, and the outcome is not as
easy to re-share with people that aren't already on that IRC channel
anyway. an example how it could be done differently is the iwp9
conferences, which always produced very interesting papers that I
enjoyed. this is a format i have missed lately, but IRC just makes it
so easy...

i heard recently a complaint that it's too hard to get patches for
9front approved and commented on. this included a second complaint
that cinap has been split into mail and irc, and i identified a belief
that cinap will only answer mail fast enough for their taste if nagged
on irc enough.
of course experience shows that many problems are most easily solved
if cinap solves them. but making more infrastructure to make cinap
solve more problems might not scale right because there's only one
cinap.

so instead i demand we find a process that allows people to *learn*
most efficiently from each other, perhaps also enabling more people to
share cinap's responsibilities.

technology and infrastructure can aid in this, but there's clearly a
bigger picture and social level that isn't as easily programmable. so
here we have to ask ourselves what we demands of others (or ourselves)
and what is really about our infrastructure.

9front sometimes moved faster, but IMO we have to allow it to move
slowly. we don't all have a well-funded research organization to pay
us for working on plan9, remember this is all free-time activity.

now, about the platforms that nobody gives any help on:

there's now a mail/web bug tracker, but i haven't seen any mails
lately. that's ok. i'm patient and still discovering.

there's web/hg fqa but it's not mounted by default in my 9front
install, so i only was able to check it rarely when i have a browser
on linux open, and sent only few patches (again, from linux and via
mail), been a while, i don't remember the process.

and there's a new 9front wiki (don't even remember where it is and if
it was web-only/werc or something else) and that is also not available
to me unless i acquire it's url and use my main browser, unless it's
already open on the other webbrowser on the other laptop or
workstation, but i can't remember.

i'm also not gonna start some kind of performance art like using
mothra either. to summarize: these web services are plainly not in my
namespace right now.
i admit it's my limitation, i'm sure i could organize my browser and
tab sessions more efficiently. but i have not (and i'm sure i'll
regret it forever).

for a longer time now, services are put online and taken offline
before anybody can get used to the systems and the processes involved
in using them (bell-labs servers, wikifs, google code servers, new
webshit werc/cat-v.org services, and most recently (for some of our
members): irc).

at the same time the 9front community is spreading and taking over
more social networks like discord, gridchat, github, bitbucket,
hackernews, twitter, matrix, mastodon, sr.ht, in turn making it harder
to track what is even going on. i try sometimes, but recently i didn't
have the time or browser real estate. it got too much.

i am experiencing a medium overload. already just mainline 9front hg
changes, mail and irc can already waste all my time. i am not able to
add even more mediums and still (ever?) engage in any significant way.

(in addition to having multiple mediums available, people (yes, me
included) demand that during one conversation the other side switches
between multiple mediums in real-time in lockstep with them.)

i don't think i'm alone, and i don't think the 9front community is the
only one suffering from medium overload.

if you can't afford all the dependencies all the different mediums
come with it creates a media gap.
the simplest example is that you might not be able to hg pull right
now as your 9front machine is not connected to the internet. you might
also not be able to copy&paste some error or make a screenshot and put
it online somewhere. you might not be able to access the fqa from
9front installer disc.
at best you might have another computer with windows/chrome, but even
then you might still not be able to copy&paste the lines you found
into your 9front, creating frequent spelling-based mistakes that waste
everybody's time on IRC when we try to help debug it...

and i think if you indiscriminately add more mediums it only gets worse.

let's not only think about what we need to do, or what we don't do,
let's also think about what we shouldn't do.

perhaps we can do with less for now. perhaps at least until we have
some more capacity worth managing with all this technology.

hiro

Re: [9front] The 9 Documentation Project

[hiro]

> I'd like compatibility with the original wikifs

didn't even think of this, but i agree, there's some value in keeping
all this old content editable!
esp. now that the bell-labs wikifs is officially gone!

is the 9p.io backup editable via 9p for everybody? are there accounts
given out for this by fish?

it would also be great if there's a technical way to somehow merge the
still relevant wikifs pages with our fqa and thus make both editable
via 9p. but we'd have to figure out how sl can re-import our changes
into .ms for the book/pdf format.

also, the current solution might not be so bad, where the fqa is
editable via hg. perhaps the main problem is that people forget what
they have access for (via hg) and where the stuff is.

we might also need some *internal* documentation? :)

Re: [9front] The 9 Documentation Project

[sirjofri+ml-9front]

Hello,

the project is not only about creating a wiki space, this is just one part that's especially useful for the information that's distributed over many blogs or hidden behind long chat logs. I often find myself interviewing kvik, burnzez or mycroftiv (and others) about how to do things that are never written anywhere else. Most of the time I try to understand this and then write an article about exactly that (on my personal blog or on 9gridchan wiki). Imo this information is good in a wiki, because other users can easily add missing information and link to other sources.

The other parts of the project (if you want to call it like that) are: improving man pages, fqa and maybe even debug messages. These are all more static because there's a review and merge process. On the other hand, collected information in a wiki can help authors to select content for the fqa.

Also don't forget /sys/doc and maybe /sys/lib/wiki. /sys/doc is a possible place to be extended with updated information. The dead /sys/lib/wiki can be revived with snapshots from the wiki. I can also think about a separate update process that automatically fetches data from the wiki and includes it into the system wiki (offline snapshot).

You see, there are many possibilities and I'd like to provide a place where plan9 users can provide useful information (guides, notes etc) that do not fit in the book styled fqa or the highly implementation specific manpages or the highly technical /sys/doc, also these articles can change quickly (sometimes daily or weekly) which would be a lot for reviewers to approve before including it into the main distribution.

Also I don't expect things to be so complex. Having a plan9 usable small and simple system (eg an official wikifs) makes more sense than hiding everything in a browser that can't even edit the pages because there's too much webshit or something like that. Also we are a small community, so providing information should be more in focus than providing nice UI and a modern web browsing experience.

sirjofri

Re: [9front] The 9 Documentation Project

[sirjofri+ml-9front]

Also I think the 9p.io wiki is public editable from plan9 systems, without auth. I believe I added a page some time ago before I switched to 9gridchan.

28.07.2020 14:22:17 hiro <23hiro@gmail.com>:

>> I'd like compatibility with the original wikifs
> 
> didn't even think of this, but i agree, there's some value in keeping
> all this old content editable!
> esp. now that the bell-labs wikifs is officially gone!
> 
> is the 9p.io backup editable via 9p for everybody? are there accounts
> given out for this by fish?
> 
> it would also be great if there's a technical way to somehow merge the
> still relevant wikifs pages with our fqa and thus make both editable
> via 9p. but we'd have to figure out how sl can re-import our changes
> into .ms for the book/pdf format.
> 
> also, the current solution might not be so bad, where the fqa is
> editable via hg. perhaps the main problem is that people forget what
> they have access for (via hg) and where the stuff is.
> 
> we might also need some *internal* documentation? :)
> 

Re: [9front] The 9 Documentation Project

[hiro]

it seems to me we might profit from making you boss of documentation,
and whatever process you find will just have to become mandatory for
the rest of us.

sounds like you are also providing useful reasoning why your process
is the right one and i'm happy to try and adopt it.

On 7/28/20, sirjofri+ml-9front@sirjofri.de
<sirjofri+ml-9front@sirjofri.de> wrote:
> Hello,
>
> the project is not only about creating a wiki space, this is just one part
> that's especially useful for the information that's distributed over many
> blogs or hidden behind long chat logs. I often find myself interviewing
> kvik, burnzez or mycroftiv (and others) about how to do things that are
> never written anywhere else. Most of the time I try to understand this and
> then write an article about exactly that (on my personal blog or on
> 9gridchan wiki). Imo this information is good in a wiki, because other users
> can easily add missing information and link to other sources.
>
> The other parts of the project (if you want to call it like that) are:
> improving man pages, fqa and maybe even debug messages. These are all more
> static because there's a review and merge process. On the other hand,
> collected information in a wiki can help authors to select content for the
> fqa.
>
> Also don't forget /sys/doc and maybe /sys/lib/wiki. /sys/doc is a possible
> place to be extended with updated information. The dead /sys/lib/wiki can be
> revived with snapshots from the wiki. I can also think about a separate
> update process that automatically fetches data from the wiki and includes it
> into the system wiki (offline snapshot).
>
> You see, there are many possibilities and I'd like to provide a place where
> plan9 users can provide useful information (guides, notes etc) that do not
> fit in the book styled fqa or the highly implementation specific manpages or
> the highly technical /sys/doc, also these articles can change quickly
> (sometimes daily or weekly) which would be a lot for reviewers to approve
> before including it into the main distribution.
>
> Also I don't expect things to be so complex. Having a plan9 usable small and
> simple system (eg an official wikifs) makes more sense than hiding
> everything in a browser that can't even edit the pages because there's too
> much webshit or something like that. Also we are a small community, so
> providing information should be more in focus than providing nice UI and a
> modern web browsing experience.
>
> sirjofri
>
>

Re: [9front] The 9 Documentation Project

[sirjofri+ml-9front]

> it seems to me we might profit from making you boss of documentation,
> and whatever process you find will just have to become mandatory for
> the rest of us.

I don't know.  That's exactly why I'm asking.  I'm happy to help, eg I
can set up a 9front wikifs server including auth and handle user
registrations as well as structuring the wiki and editing it.  I can
also help managing changes and user feedback as well as asking
original authors to contribute to the wiki.

I can also try collecting wiki content and format it for inclusion
into official 9front, if wanted, as well as sending patches to the
fqa, but I want to encourage people to also do that.

I hope we find a good and helpful process for all users and devs, and
support developers so they don't need to handle everything.  Also I
hope I don't need to do everything alone, but I guess that's often the
case in an open source world where no money is involved.


sirjofri

Re: [9front] The 9 Documentation Project

[hiro]

we need a clear, sane, documented process how to contribute.

what you are describing sounds like it could become that. of course
once we tested it out we need to also decide to start enforcing it,
too. somehow last time the part of the system that i knew about didn't
feel like it made enough sense to force it on anybody.

and yes, for some things sometimes you're the only one, i'm sure you
will be joined by others.

let's just hope sl agrees! :)

On 7/28/20, sirjofri+ml-9front@sirjofri.de
<sirjofri+ml-9front@sirjofri.de> wrote:
>> it seems to me we might profit from making you boss of documentation,
>> and whatever process you find will just have to become mandatory for
>> the rest of us.
>
> I don't know.  That's exactly why I'm asking.  I'm happy to help, eg I
> can set up a 9front wikifs server including auth and handle user
> registrations as well as structuring the wiki and editing it.  I can
> also help managing changes and user feedback as well as asking
> original authors to contribute to the wiki.
>
> I can also try collecting wiki content and format it for inclusion
> into official 9front, if wanted, as well as sending patches to the
> fqa, but I want to encourage people to also do that.
>
> I hope we find a good and helpful process for all users and devs, and
> support developers so they don't need to handle everything.  Also I
> hope I don't need to do everything alone, but I guess that's often the
> case in an open source world where no money is involved.
>
>
> sirjofri
>
>

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

On July 28, 2020 10:16:42 AM EDT, hiro <23hiro@gmail.com> wrote:
>we need a clear, sane, documented process how to contribute.
>
>what you are describing sounds like it could become that. of course
>once we tested it out we need to also decide to start enforcing it,
>too. somehow last time the part of the system that i knew about didn't
>feel like it made enough sense to force it on anybody.
>
>and yes, for some things sometimes you're the only one, i'm sure you
>will be joined by others.
>
>let's just hope sl agrees! :)
>
>On 7/28/20, sirjofri+ml-9front@sirjofri.de
><sirjofri+ml-9front@sirjofri.de> wrote:
>>> it seems to me we might profit from making you boss of
>documentation,
>>> and whatever process you find will just have to become mandatory for
>>> the rest of us.
>>
>> I don't know.  That's exactly why I'm asking.  I'm happy to help, eg
>I
>> can set up a 9front wikifs server including auth and handle user
>> registrations as well as structuring the wiki and editing it.  I can
>> also help managing changes and user feedback as well as asking
>> original authors to contribute to the wiki.
>>
>> I can also try collecting wiki content and format it for inclusion
>> into official 9front, if wanted, as well as sending patches to the
>> fqa, but I want to encourage people to also do that.
>>
>> I hope we find a good and helpful process for all users and devs, and
>> support developers so they don't need to handle everything.  Also I
>> hope I don't need to do everything alone, but I guess that's often
>the
>> case in an open source world where no money is involved.
>>
>>
>> sirjofri
>>
>>

agree to what, exactly? just do it.

including stuff in the distribution would have to be very selective because of the danger of filling up the iso. i don't think requiring network connectivity for access to a moving target like community generated documentation would be onerous. rather, it's part of the definition: network effects require a network. (i do understand people would like a more coherent and directly applicable overview included with the system, but I think that's a separate issue.)

i think the fqa/book can just remain a fictional work created by me. its present form became very inflexible owing to the fact that after years of nobody contributing, but everyone always complaining, i went ahead and made it into a complete, printed book. i make no claim of ownership over 9front documentation, but i don't think it makes sense to bikeshed the existing (working) resource with a bunch of knobs and levers that will only get pulled enough times to run the car off the road, shortly before it is abandoned forever as it is now a smoldering heap of unrecognizable twisted metal, but thank god it has two steering wheels. instead, i advocate that any suggested replacement be created in parallel. i'm happy to link to any relevant resources in the fqa itself. grid stuff is already on my todo.

if we do decide to replace the fqa as the official resource, or i'm replaced as editor, i would be happy to fork my version and continue self-publishing it as fiction, even to the point of moving it away from 9front.org. i was mindful of this possibility when creating the book. the indicia claims it is released under a public domain license. in the end i don't think it really matters much if the book is considered official. anyone, anywhere should always feel free to pillage it for content.

all of this is to say, please just do it. the fqa only exists because nobody else made anything first. it took a while for me to follow through on putting it together, and i readily acknowledge that what is there is woefully insufficient. i remain hopeful the community can muster the effort to improve upon the current situation.

sl

Re: [9front] The 9 Documentation Project

[ori]

>> it seems to me we might profit from making you boss of documentation,
>> and whatever process you find will just have to become mandatory for
>> the rest of us.
> 
> I don't know.  That's exactly why I'm asking.  I'm happy to help, eg I
> can set up a 9front wikifs server including auth and handle user
> registrations as well as structuring the wiki and editing it.  I can
> also help managing changes and user feedback as well as asking
> original authors to contribute to the wiki.
> 
> I can also try collecting wiki content and format it for inclusion
> into official 9front, if wanted, as well as sending patches to the
> fqa, but I want to encourage people to also do that.
> 
> I hope we find a good and helpful process for all users and devs, and
> support developers so they don't need to handle everything.  Also I
> hope I don't need to do everything alone, but I guess that's often the
> case in an open source world where no money is involved.
> 
> 
> sirjofri

The people doing the work get to pick the tools -- really, I think that's
all there is to it. If you want to write docs, and you want to write docs
using wikifs, then that's the way to go. If you want to piss it into the
snow, 

Second, trying to gather volunteers for a grand project before it even
starts doesn't have a high success rate. The way these things typically
work is that someone starts doing the work, others start to give feedback
and then find themselves involved.

Pick a target, write something, and ask for feedback.

Re: [9front] The 9 Documentation Project

[ori]

> i think the fqa/book can just remain a fictional work create
>d by me. its present form became very inflexible owing to the
> fact that after years of nobody contributing, but everyone
> always complaining

It's less inflexible than advertised -- the patches I've
submitted got applied in short order. I strongly encourage
others to try.

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

On July 28, 2020 11:12:53 AM EDT, ori@eigenstate.org wrote:
>> i think the fqa/book can just remain a fictional work create
>>d by me. its present form became very inflexible owing to the
>> fact that after years of nobody contributing, but everyone
>> always complaining
>
>It's less inflexible than advertised -- the patches I've
>submitted got applied in short order. I strongly encourage
>others to try.

i think having a single gatekeeper rankles the foss sensibility, even of nobody is necessarily trying to pass anything through the gate at the moment. likewise, i think a premium is placed on officially stamped propaganda, as opposed to merely correct propaganda.

sl

Re: [9front] The 9 Documentation Project

[hiro]

i prefer having a single gatekeeper and a single official place of
documentation and no official or non-official forks of the fqa

Re: [9front] The 9 Documentation Project

[ori]

> i think having a single gatekeeper rankles the foss sensibility,
> even of nobody is necessarily trying to pass anything through the gate
> at the moment.  likewise, i think a premium is placed on officially
> stamped propaganda, as opposed to merely correct propaganda.

I think that the FQA is one of the best things that happened
to plan 9 documentation in a long time, and I'm very happy
with how well it's maintained.

Re: [9front] The 9 Documentation Project

[Kurt H Maier]

On Tue, Jul 28, 2020 at 10:37:44AM -0700, ori@eigenstate.org wrote:
> > i think having a single gatekeeper rankles the foss sensibility,
> > even of nobody is necessarily trying to pass anything through the gate
> > at the moment.  likewise, i think a premium is placed on officially
> > stamped propaganda, as opposed to merely correct propaganda.
> 
> I think that the FQA is one of the best things that happened
> to plan 9 documentation in a long time, and I'm very happy
> with how well it's maintained.

I strongly agree.  I don't see a need for FQA management to change.
Other documentation efforts can happily live alongside it.  

I also think the current solution (cutting an ISO and a dash-1 pdf at 
the same time) is fine and I don't think it's too much to ask people 
to download a pdf if they want it on their system.  There's no reason to
integrate the FQA into the main source repo; it's just an hg clone away.

khm

Re: [9front] The 9 Documentation Project

[cinap_lenrek]

i think alot of confusion comes from the auth= atribute in the
ip/ipnet= entry vs. auth= attribute on the authdom= entry.

the auth= attribute from ip/ipnet is actually only used by terminals
that netboot! it is an attribute that the dhcp server will put in
a special option to ship it to the client so the client can dial
the authentication server to authenticate against the (root)
fileserver before having access to ndb.

but once you'r booted, factotum will actually look for authdom=
attribute in ndb to resolve the authentication server for a particular
domain presented in the p9any handshake, and IGNORE the auth=
attribute on a host or ipnet completely.

the protocol (omiting nonce and dh/dp9ik steps) works like this:

0) client connects to server
1) server presetns a list of domains, host identities and protocols
2) client picks a protocol and uses the domain and find the authentication
server for the domain and does a ticket request
3) decrypts client part of the ticket with its own password and extracts shared secret
4) forwards the server part of the ticket to the server
5) server decrypts the ticket with his own password and extracts shared secret
6) client and server verify that they each other known the shared secret
7) success. optinally use shared secret to establish encrypted channel (tlssrtv)

the step that bugs most people is 2), as in the protocol, only
the authentication DOMAIN is send over the wire. finding the AS
is the job of the CLIENT.

theres also a trick: if you use a dns domain name as the authdom,
then you can register an A/AAAA record for p9auth.$authdom and factotum;
if it can't find authdom= attribute in ndb; will attempt to contact
p9auth.$authdom instead as the auth server. then the client doesnt
need to add a authdom= entry in its ndb!

kerberos solves this with SRV records.

the error that happens is that people miss the authdom= attribute, and
assume the authentication server is per network. no. it is not. it is
just a bootstrap mechanism! and the real mechanism is apparently not
well known to many people.

the issue with dns is that newbies dont have dns under their control.
so p9auth is out. srv records is out. the only thing left what we can
do is find ways to avoid this hack and deprecate the auth= attribute.
maybe have dhcpd automatically determine authdom by dialing the root
fileserver and doing the resolution of authserver on behalf of the
client.

or we could ship all the authdoms= from ndb in a dhcp option.

maybe factotum itself could provide a hint over p9any protocol?
like we have the service factotum look into ndb and provide a list of
hints of the external addresses of the authservers for each key?

in any case, i think we could avoid alot of confusion by improving
the way of this bootstrap mechanism works.

--
cinap

Re: [9front] The 9 Documentation Project

[ori]

> Also I think the 9p.io wiki is public editable from plan9 systems,
> without auth.  I believe I added a page some time ago before I
> switched to 9gridchan.

It is.

Re: [9front] The 9 Documentation Project

[Ethan Gardener]

On Tue, Jul 28, 2020, at 8:10 PM, cinap_lenrek@felloff.net wrote:
> i think alot of confusion comes from the auth= atribute in the
> ip/ipnet= entry vs. auth= attribute on the authdom= entry.
...
> but once you'r booted, factotum will actually look for authdom=
> attribute in ndb to resolve the authentication server for a particular
> domain presented in the p9any handshake, and IGNORE the auth=
> attribute on a host or ipnet completely.

i don't think that particular thing got me, but thanks for the clarification. (i think you probably explained it to me in irc, years ago.)

> the protocol (omiting nonce and dh/dp9ik steps) works like this:
> 
> 0) client connects to server
> 1) server presetns a list of domains, host identities and protocols
> 2) client picks a protocol and uses the domain and find the 
> authentication
> server for the domain and does a ticket request
> 3) decrypts client part of the ticket with its own password and 
> extracts shared secret
> 4) forwards the server part of the ticket to the server
> 5) server decrypts the ticket with his own password and extracts shared 
> secret
> 6) client and server verify that they each other known the shared secret
> 7) success. optinally use shared secret to establish encrypted channel 
> (tlssrtv)
> 
> the step that bugs most people is 2), as in the protocol, only
> the authentication DOMAIN is send over the wire. finding the AS
> is the job of the CLIENT.

i think you told me all this years ago, but i still had trouble. (this is good; it's better to see it in a document rather than chat.) i think my problem was i kept getting confused about the syntax of ndb. what on earth is a "tuple" when it's not one of python's immutable lists? a key-value pair? also, i was never clear on where to put things, despite your help. there's these different sections with different names which make no sense, and it makes no sense why you can't put some netwide-default things in what appears to be the netwide-defaults section... that's what i felt, anyway.


> the issue with dns is that newbies dont have dns under their control.
> so p9auth is out. srv records is out. the only thing left what we can
> do is find ways to avoid this hack and deprecate the auth= attribute.
> maybe have dhcpd automatically determine authdom by dialing the root
> fileserver and doing the resolution of authserver on behalf of the
> client.

this! i'm pretty sure my plan 9 machines worked best when i statically set their ips. i also set them up on my natbox so it wouldn't conflict, and when it was time to reconfigure, i thought "why am i setting these twice?" and made it worse. also... i think that one time i set the ips statically is probably the time you helped me the most. ;)

dhcpd dialing the root fileserver is probably a good idea. more automatic *and* less confusing. no idea about the other two methods, i can't visualize them so easily, but if they have the same result, that's fine with me.

> in any case, i think we could avoid alot of confusion by improving
> the way of this bootstrap mechanism works.

some confusion, certainly.

something of the same sort of bootstrap problem is on the horizon of my forth. not with the network, but with defining things more than once because the regular definition isn't available until after a bootstrap definition is made. i'll figure it out.

"an adequate bootstrap is a contradiction in terms." - linus torvalds. i'm not sure about 'adequate', but substitute 'clean' and the statement works quite well.

Re: [9front] The 9 Documentation Project

[sl]

> I put up code.9front.org/wiki mostly so we can demonstrate that large
> swaths of time go by with no changes, and the changes that show up are
> generally from a handful of people.  I don't really like wikis as
> documentation and/or knowledge bases because they only work when a
> preponderance of users contribute.

i have to apologize because 1.) i forgot this was even there, and 2.)
i didn't know people had added anything to it, at all.


> I would much prefer thet see
> specific sections of the FQA overhauled in a thoughtful manner, but I
> sure do not have free time for that at the moment.

fqa7 needs help.


> The problem with the current introductory garden path is that each piece
> of advice reults in roadblocks to future pieces of advice, e.g. "set up
> a terminal that can accept cpu connections, now set up these services on
> another machine, now tear down step one and rebuild it in step two's
> image" etc.  It works for "zero to running" but it sucks as a
> pedagogical approach, as not all learners do well with the "draw the
> rest of the fucking owl" approach.
> 
> Old electronics manuals (specifically, here thinking of Textronics
> oscilloscope manuals) used to have a section entitled "Theory of
> Operation" which went over at a high level what each component and/or
> panel button did and why, culminating in an explanation of how they
> worked together in common scenarios.  Such a document explaining what
> these services (ndb, factotum, secstore, rpcu, etc) do without getting
> distracted by administration instructions may be a valuable document.
> 
> "What does this tool do and when do I use it" is a fundamentally
> different question than "how do I operate this tool" and I think mixing
> them in the FQA may be doing a disservice to some segment of the
> readership.  I personally prefer the mixed approach, but I'm not
> everyone.  Yet.

i agree we need something like this. i've dabbled with every piece
except assembling a narrative.

sl

Re: [9front] The 9 Documentation Project

[magma698hfsp273p9f]

sirjofri+ml-9front@sirjofri.de writes:

> I thought about this some time and think we can do documentation
> better. Of course we have the very good fqa (which is 9front "only")
> and the official man pages as well as other documentation sources and
> guides. Most of these guides are distributed in various personal blogs
> and contribution to man pages and the fqa takes time (patch creation,
> review).

First, let me say that I think a "9 Documentation Project" is a great
idea.  Documentation is one of the places where Plan 9 (of all flavors,
including Inferno) is most lacking.  When I was first learning Linux, I
leaned heavily on the Linux Documentation Project (TLDP) and read many
of the "HOWTO"s in order to learn how Linux works and how to use it.
The Plan 9 family could benefit immensely from a similar body of
documentation.  s/TLDP/T9DP/ :)

> My dream is something like a publicly available wiki system (wikifs?)
> with good structure where every nine user can contribute to without
> review.

I would propose using a Web-accessible Wiki which manages changes using
a publicly-accessible git repository on the backend.  (Yes.  Here's
why.)

Some problems with Plan 9's wikifs:

  1.  The last time I tried using it via the Web, the Web interface
      didn't permit anyone to make edits.

  2.  Using wikifs requires acme, which means that a contributor must
      already have Plan 9 set-up and running and know how to use it.

  3.  It requires connection via 9p.  This means that Plan 9 must
      already be set-up, AND requires a live connection to the Internet.

  4.  It is hard to properly curate content and track your contributions
      on a Wiki when anything can be edited, by anyone, at any time.

  5.  It requires contributors to learn the Wiki mark-up language.
      That's not a huge hurdle, but requires source which is hard to
      read and annoying to maintain.

  6.  It is difficult to maintain cross-references between pages on a
      Wiki.  When pages are renamed, when pages are consolidated, or
      when information is relocated from one page to another, references
      to those pages need to be updated.

  7.  When I tried to use Wikifs from acme, about half the time, it
      didn't work.  I'd keep receiving error messages that the other end
      "hung-up" on me.

Some advantages of using a git-backed Wiki:

  A.  It would be accessible via the Web, which makes it accessible to
      most people, whether they are on Plan 9 or another device; whether
      they are just learning how to use Plan 9 or are a seasoned user
      who just needs to look something up; and whether they are
      correcting a simple typo or contributing an entirely new article.

  B.  It provides a place to centralize things like /sys/doc, /man, the
      FQA, and Wiki pages (possibly on separate branches).  When
      spinning a new release of the OS, it'd be a simple matter to
      pull-in all the latest changes.

  C.  It provides a way for contributors to curate, or take ownership,
      of their own content and contributions.  By maintaining their own
      branch, users can keep track of their contributions, vet changes
      made by others, and accept the edits/improvements of which they
      approve.  (Changes to the default branch, of course, could be made
      by anyone, whether using git or the Web interface.)  This removes
      the need for a single "gatekeeper" to approve changes.

  D.  DVCS like git already have well-understood mechanisms for tracking
      when files get renamed.  When someone follows a link to a page
      which has been renamed, the Wiki can find the new name of the page
      and issue an HTTP 304 redirect.

  E.  Because Plan 9, including its documentation, is so heavily
      text-based, the problem of cross-referencing pages becomes easier
      to solve.  Text-based automated tools can scan the documentation,
      flagging and/or fixing-up cross references.

  F.  git would make it easy to check-out the latest version of (some or
      all of) the docs, or do a full clone of the repo to get all the
      revisions on all the branches.

  G.  Power users are often frustrated by having to "point, click, type,
      scroll, repeat" as is often required by Web interfaces.  Using
      git, a power user could just make a change using a text editor,
      and commit from the command line, without even having to touch a
      Web browser.

  H.  git solves the problem of off-line use.  Documentation checked-out
      from the repo can be read entirely off-line, and changes that are
      made off-line can be committed whenever an Internet connection
      becomes available.

  I.  Historical versions of documentation can be archived, providing a
      sort of "time machine" for the documentation.

  J.  A branch (or a separate repo) could be used to archive the 9front
      mailing list, keep logs of discussion on the IRC channel, etc.

  K.  Because the documentation is almost entirely text, one could
      "grep" all the docs (and/or the mailing list, IRC channel, etc.)
      for answers, in a single place, before asking a question.  The
      grep/search could be entirely off-line, without having to rely on
      a Web search engine to find relevant information.  (Of course, any
      base64-encoded e-mail messages would have to be converted to
      UTF-8, but that's easy.)

  L.  A branch (or separate repo) could even be used as an informal bug
      tracker.  Issues could be added, and commented upon, etc. either
      from the Web interface, or from git.

Because much of the work done by a Wiki (tracking changes) is already
done by git, it shouldn't be too difficult to write a git-backed Wiki.
In fact, it's likely that one or more implementations already exist.  In
order to use one of these for "T9DP", it would just need to be ported to
Plan 9 (ideally, by translating it into Limbo).  Because Inferno has a
Limbo compiler that runs on Plan 9, the Wiki server would be able to
compile and run on any 9 variant: 9front, Inferno, etc.

Re: [9front] The 9 Documentation Project

[kvik]

> I would propose using a Web-accessible Wiki which manages changes using
> a publicly-accessible git repository on the backend.

Good and clear points.

For the past two days I have been working on mostly such a wiki.

I need to be places in a few minutes so there's no time to discuss some
finer points or goals and intentions, but I hope enough is already
described here:

	http://docs.a-b.xyz

Some technical detail on the implementation is mentioned here:

	http://docs.a-b.xyz/this.html

It is a work in progress but a few people have already contributed some
pages and made very valuable suggestions and comments.

Thanks again for that!

Re: [9front] The 9 Documentation Project

[ori]

>   2.  Using wikifs requires acme, which means that a contributor must
>       already have Plan 9 set-up and running and know how to use it.

I just want to point out that it's unlikely any good contributions
will come from someone that doesn't have plan 9.

Re: [9front] The 9 Documentation Project

[Kurt H Maier]

On Thu, Jul 30, 2020 at 06:12:59PM +0000, magma698hfsp273p9f@icebubble.org wrote:
> Some problems with Plan 9's wikifs:
> 
>   1.  The last time I tried using it via the Web, the Web interface
>       didn't permit anyone to make edits.

Any wiki is a high-profile spam target.  Mitigating that spam is
labor-intensive.  Be prepared to deal with this.

>   2.  Using wikifs requires acme, which means that a contributor must
>       already have Plan 9 set-up and running and know how to use it.

As much as I dislike acme, plan9port acme supports this.  But on a
larger note, why do we need documentation contributions from people who
are not using the system?  Surely other support channels would be more
appropriate?

>   4.  It is hard to properly curate content and track your contributions
>       on a Wiki when anything can be edited, by anyone, at any time.

This objection seems to be in conflict with the objections about how
hard it is to accept contributions from anyone on any platform. 

>   I.  Historical versions of documentation can be archived, providing a
>       sort of "time machine" for the documentation.

This is what yesterday(1) is for.

>   J.  A branch (or a separate repo) could be used to archive the 9front
>       mailing list, keep logs of discussion on the IRC channel, etc.

Now we've moved from "I want a wiki whose source is in a dvcs" to "we
should just stop using fileservers"

>   K.  Because the documentation is almost entirely text, one could
>       "grep" all the docs (and/or the mailing list, IRC channel, etc.)
>       for answers, in a single place, before asking a question.  The
>       grep/search could be entirely off-line, without having to rely on
>       a Web search engine to find relevant information.  (Of course, any
>       base64-encoded e-mail messages would have to be converted to
>       UTF-8, but that's easy.)

This is already the case by mounting the wiki and copying it to your
computer.

> Because much of the work done by a Wiki (tracking changes) is already
> done by git, it shouldn't be too difficult to write a git-backed Wiki.
> In fact, it's likely that one or more implementations already exist.  In
> order to use one of these for "T9DP", it would just need to be ported to
> Plan 9 (ideally, by translating it into Limbo).  Because Inferno has a
> Limbo compiler that runs on Plan 9, the Wiki server would be able to
> compile and run on any 9 variant: 9front, Inferno, etc.

There are about sixteen thousand dvcs-backed wiki programs; many of them
already work on Plan 9.  None of them are written in Limbo, though.

I don't like the idea of abandoning 9p in favor of git (or any other
dvcs, for that matter).  However, if someone puts up a wiki, let's
migrate the data from code.9front.org/wiki to it and I'll set up a
redirect.

In my opinion, wikis in general are trash piles where information goes
to die.  The defining feature of a wiki, inter-document linking, is
fragile, almost entirely useless, and labor-intensive to maintain.
Tracking changes is a red herring; the wiki itself doesn't even need to
do this.  What it DOES need to do is process every document, either at
commit time or at render time, looking for carefully-crafted tokens,
figuring out whether the corresponding document exists, and generating
relevant hyperlinks in the output.  The only circumstances under which
this provides value involve a phenomenally large userbase who is
extremely active.

Instead I recommend using whatever storage you like (9p server, dvcs, 
dvcs ON a 9p server, whatever) and then setting up an automated pipeline
to generate HTML output, which you then serve.  Your bespoke Limbo
program then becomes much simpler: it just needs to let a given spammer
edit the source document.  This is a much simpler and
lower-resource-requirement task than implementing a wiki, with all of
its useless WikiLinks document-parsing rabbit holes.  This is in fact
how werc wikis work.  Nobody's expanded werc's wiki software to be
dvcs-backed because the filesystem is expected to be useful.  However,
given that the werc wiki, dirdir, is forty lines of rc, I'd bet it would
be pretty easy to do.


The above text is based on having spent a lot of time and effort hosting
similar software as part of similar endeavors over the years.  I will
not be offended if it is ignored.  When consensus is reached and
Documentation Valhalla is made real I'll happily redirect to it and
experience a real sense of joy as I turn off the old wiki.

khm

Re: [9front] The 9 Documentation Project

[Eckard Brauer]

> I just want to point out that it's unlikely any good contributions
> will come from someone that doesn't have plan 9.

Seems to be a chicken-egg-pronlem.

Just for my 2 cents - I'm not at the point giving hints to 9front
community.

IMHO is sort of "multidimensional work-in-progress". "Work-in-progress"
is obvious, as both documentation itself and the system with all its
facilities do evolve, so we have at best one, usually at least two time
lines, multidimensional, as we/you have a couple of groups consuming
documentation, with slightly different or even orthogonal points (and
directions) of view.

So we should conequently be able to put together /pieces/ of different
documentation ressources into one single documentation. That includes
taking snapshots of given points in time as well as heavy linking or
taking of (primary) ressources of different types.

For what I know, no single system seems to make that possible or
support it, and I'd be in a doubt that we could establish a new
standard.

All beside that means to keep tho current system, where newcomers (like
myself) remain confronted with tips like "read this or that again until
you understand", where intermediate users/developers have to go through
a good couple of documents each and every time.

As written already - just some maybe stupid ideas..

Ecki

Re: [9front] The 9 Documentation Project

[Romano]

+1

On July 30, 2020 6:54:05 PM UTC, ori@eigenstate.org wrote:
>>   2.  Using wikifs requires acme, which means that a contributor must
>>       already have Plan 9 set-up and running and know how to use it.
>
>I just want to point out that it's unlikely any good contributions
>will come from someone that doesn't have plan 9.

Re: [9front] The 9 Documentation Project

[Ethan Gardener]

On Thu, Jul 30, 2020, at 8:15 PM, Kurt H Maier wrote:
> On Thu, Jul 30, 2020 at 06:12:59PM +0000, 
> magma698hfsp273p9f@icebubble.org wrote:
> > Some problems with Plan 9's wikifs:
> > 
> >   1.  The last time I tried using it via the Web, the Web interface
> >       didn't permit anyone to make edits.
> 
> Any wiki is a high-profile spam target.  Mitigating that spam is
> labor-intensive.  Be prepared to deal with this.

yeah, we don't need another labour sink.

> >   2.  Using wikifs requires acme, which means that a contributor must
> >       already have Plan 9 set-up and running and know how to use it.
> 
> As much as I dislike acme, plan9port acme supports this.  But on a
> larger note, why do we need documentation contributions from people who
> are not using the system?  Surely other support channels would be more
> appropriate?

i considered contributions from users struggling to set up, but honestly, those contributions should go to mailing list or bug tracker. they can later be condensed for the wiki by the user or others. this has worked with the fqa, if i remember right.

> >   4.  It is hard to properly curate content and track your contributions
> >       on a Wiki when anything can be edited, by anyone, at any time.
> 
> This objection seems to be in conflict with the objections about how
> hard it is to accept contributions from anyone on any platform. 

doesn't wikifs track who last edited the file? some plan 9 filesystems do.

> >   I.  Historical versions of documentation can be archived, providing a
> >       sort of "time machine" for the documentation.
> 
> This is what yesterday(1) is for.

i cautiously agree. yesterday won't catch multiple changes to the same file in the same day. how many manic monkeys are going to be working on this? speaking of manic monkeys... when i edit wikis, i generally find myself wishing all my changes to a page on a given day would appear as a single commit. there are times when i want the opposite. i don't think any wiki allows for both, not even those with a 'minor edit' flag.

> >   J.  A branch (or a separate repo) could be used to archive the 9front
> >       mailing list, keep logs of discussion on the IRC channel, etc.
> 
> Now we've moved from "I want a wiki whose source is in a dvcs" to "we
> should just stop using fileservers"

EVIL!!! lol

my primary opinion on all of this is: if you have a good tool, use it and stop requiring users to learn other junk. on the other hand, 9front itself uses hg because users were dissatisfied with the lack of commit messages. this also applies to wikis to some extent. i don't see the problem for wikis; summaries are nice, but diffs are more useful. 

remember that you can grep or diff wikifs without having to resort to $scm's special tools *or* addressing history in a tool-specific way. i dare to say the most loved facet of plan 9 is that the system is unified and fairly clean. is polluting it with scms worth the cost?

i'm not going to argue this point further because frankly, parts of plan 9 are already not unified and clean. my development efforts are now going into an experiment to see if better tools are possible.

> >   K.  Because the documentation is almost entirely text, one could
> >       "grep" all the docs (and/or the mailing list, IRC channel, etc.)
> >       for answers, in a single place, before asking a question.  The
> >       grep/search could be entirely off-line, without having to rely on
> >       a Web search engine to find relevant information.  (Of course, any
> >       base64-encoded e-mail messages would have to be converted to
> >       UTF-8, but that's easy.)
> 
> This is already the case by mounting the wiki and copying it to your
> computer.

indeed! this point looks like a case of techie brain failure syndrome, a horribly common problem plan 9 was thankfully largely free of. i think it's to do with trying to cram too much into the working memory; there's a limit to what it can hold. just like multi-tasking, it makes you feel good, but that's just because you're getting high off your own neurochemicals. you're actually *less* capable when you try too hard.

you know, the above point may be directly applicable to using scms with their arcane things to remember on top of the code you're writing. however, it's definitely directly applicable to coming up with analysis scripts for dump or wikifs. (despite plan 9's lovely unified regexps.) which is the lesser evil? don't ask me, i'm trying to develop something better than either. :}

> > Because much of the work done by a Wiki (tracking changes) is already
> > done by git, it shouldn't be too difficult to write a git-backed Wiki.
> > In fact, it's likely that one or more implementations already exist.  In
> > order to use one of these for "T9DP", it would just need to be ported to
> > Plan 9 (ideally, by translating it into Limbo).  Because Inferno has a
> > Limbo compiler that runs on Plan 9, the Wiki server would be able to
> > compile and run on any 9 variant: 9front, Inferno, etc.
> 
> There are about sixteen thousand dvcs-backed wiki programs; many of them
> already work on Plan 9.  None of them are written in Limbo, though.

indeed. and speaking from experience, things written in limbo do not fit into plan 9 any better than things written in posix c.

now, i'd better get brunch and stop getting high off my own neurochemicals from just trying to understand this overthought mess. last comment: i think it's very well worth listening to khm & sl, they have practical experience.

> I don't like the idea of abandoning 9p in favor of git (or any other
> dvcs, for that matter).  However, if someone puts up a wiki, let's
> migrate the data from code.9front.org/wiki to it and I'll set up a
> redirect.
> 
> In my opinion, wikis in general are trash piles where information goes
> to die.  The defining feature of a wiki, inter-document linking, is
> fragile, almost entirely useless, and labor-intensive to maintain.
> Tracking changes is a red herring; the wiki itself doesn't even need to
> do this.  What it DOES need to do is process every document, either at
> commit time or at render time, looking for carefully-crafted tokens,
> figuring out whether the corresponding document exists, and generating
> relevant hyperlinks in the output.  The only circumstances under which
> this provides value involve a phenomenally large userbase who is
> extremely active.
> 
> Instead I recommend using whatever storage you like (9p server, dvcs, 
> dvcs ON a 9p server, whatever) and then setting up an automated pipeline
> to generate HTML output, which you then serve.  Your bespoke Limbo
> program then becomes much simpler: it just needs to let a given spammer
> edit the source document.  This is a much simpler and
> lower-resource-requirement task than implementing a wiki, with all of
> its useless WikiLinks document-parsing rabbit holes.  This is in fact
> how werc wikis work.  Nobody's expanded werc's wiki software to be
> dvcs-backed because the filesystem is expected to be useful.  However,
> given that the werc wiki, dirdir, is forty lines of rc, I'd bet it would
> be pretty easy to do.
> 
> 
> The above text is based on having spent a lot of time and effort hosting
> similar software as part of similar endeavors over the years.  I will
> not be offended if it is ignored.  When consensus is reached and
> Documentation Valhalla is made real I'll happily redirect to it and
> experience a real sense of joy as I turn off the old wiki.
> 
> khm
>

Re: [9front] The 9 Documentation Project

[kvik]

For the past few days I procrastinated on a school project, which
resulted in what you are free to call a wiki. [1]

It is proudly a dumping ground for 9-adjacent information, some of which
you could call documentation.

The intention and hope for it is to house information that might not
neatly fit the finite purpose of a manual page, the book format of the
FQA, or the importance and outdatedness of a /sys/doc paper.  I also see
it reasonably serving the role of a working bench for documents that
might become a part of the above forms of documentation.

This is a lot of results to hope for from making and hosting some
software — hope that I would have lost without the enthusiasm shown by
the few people already making contributions in code and content.

Some technical details behind this are described at [2].

Not much is set in stone just yet, and I'd love making a system people
will enjoy using, so feel free to drop concrete suggestions if you have
some.

[1] http://docs.a-b.xyz
[2] http://docs.a-b.xyz/this.html

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

On July 31, 2020 9:44:33 AM EDT, kvik@a-b.xyz wrote:
>For the past few days I procrastinated on a school project, which
>resulted in what you are free to call a wiki. [1]
>
>It is proudly a dumping ground for 9-adjacent information, some of
>which
>you could call documentation.
>
>The intention and hope for it is to house information that might not
>neatly fit the finite purpose of a manual page, the book format of the
>FQA, or the importance and outdatedness of a /sys/doc paper.  I also
>see
>it reasonably serving the role of a working bench for documents that
>might become a part of the above forms of documentation.
>
>This is a lot of results to hope for from making and hosting some
>software — hope that I would have lost without the enthusiasm shown by
>the few people already making contributions in code and content.
>
>Some technical details behind this are described at [2].
>
>Not much is set in stone just yet, and I'd love making a system people
>will enjoy using, so feel free to drop concrete suggestions if you have
>some.
>
>[1] http://docs.a-b.xyz
>[2] http://docs.a-b.xyz/this.html

thank you!

sl

Re: [9front] The 9 Documentation Project

[Ethan Gardener]

On Fri, Jul 31, 2020, at 2:44 PM, kvik@a-b.xyz wrote:
> For the past few days I procrastinated on a school project, which
> resulted in what you are free to call a wiki. [1]
> 
> It is proudly a dumping ground for 9-adjacent information, some of which
> you could call documentation.
> 
> The intention and hope for it is to house information that might not
> neatly fit the finite purpose of a manual page, the book format of the
> FQA, or the importance and outdatedness of a /sys/doc paper.  I also see
> it reasonably serving the role of a working bench for documents that
> might become a part of the above forms of documentation.
> 
> This is a lot of results to hope for from making and hosting some
> software — hope that I would have lost without the enthusiasm shown by
> the few people already making contributions in code and content.
> 
> Some technical details behind this are described at [2].
> 
> Not much is set in stone just yet, and I'd love making a system people
> will enjoy using, so feel free to drop concrete suggestions if you have
> some.
> 
> [1] http://docs.a-b.xyz
> [2] http://docs.a-b.xyz/this.html

Good to see something's being done!

I find I'm curiously pleased to see rc-httpd is not involved. Must be my love for diversity.

Re: [9front] The 9 Documentation Project

[magma698hfsp273p9f]

"Ethan Gardener" <eekee57@fastmail.fm> writes:

> you know, the above point may be directly applicable to using scms
> with their arcane things to remember on top of the code you're
> writing. however, it's definitely directly applicable to coming up
> with analysis scripts for dump or wikifs. (despite plan 9's lovely
> unified regexps.) which is the lesser evil? don't ask me, i'm trying
> to develop something better than either. :}

Why would you object to anyone doing a text search on the docs?  That
seems like it would be a very convenient benefit of having text-based
documentation in a unified tree.  Plan 9's intentional choice to use
text-based mechanisms no doubt anticipated synergies such as this.  I
don't know about you, but I regularly search my mailbox files using
grep.  That's one of the reasons why I chose a MUA which stores messages
in plain text.  They're more useful, that way.

Re: [9front] The 9 Documentation Project

[Ethan Gardener]

On Mon, Aug 3, 2020, at 7:50 PM, magma698hfsp273p9f@icebubble.org wrote:
> Why would you object to anyone doing a text search on the docs?  

I'm not, I'm objecting to the difficulty and failures I got when I tried to do it.

Re: [9front] The 9 Documentation Project

[Ethan Gardener]

On Thu, Jul 30, 2020, at 4:12 AM, Michael Misch wrote:
> I have no weight nor should you care about my opinion, but what sl just 
> posted was a breath of fresh air

What sl posts often is.

Re: [9front] The 9 Documentation Project

[Kurt H Maier]

On Thu, Jul 30, 2020 at 10:19:46AM +0200, hiro wrote:
> sl, it sounds like you're arguing everything should be decentralized
> and there should be no hierarchy, and yet the reality is power is
> centralized and there is hierarchy and things are enforced (for
> example what goes on the 9front website, or the minimum quality policy
> for anything that goes into 9front, including the man pages
> obviously).
> 
> being included on a 9front.org subdomain the fqa is clearly considered
> official by visitors.
> why do you insist you're some kind of wild rebel if the reality is
> that powers have been granted to you specifically. is this somehow
> troubling to you?
> 
> of course hidden power structures are easier enforced and get
> questioned and attacked less often, but i can't beleive that would be
> your motivation.
> 
> the reason i'm bringing this up is bec. with some alignment (i'm sure
> there's enough overlap in goals to allow for this) the end result will
> have a higher quality for all of us and we don't have to splinter into
> multiple communities that have an even harder time communicating and
> collaborating than what is currently the case (there were specific
> complaints about this, so i believe we should make it better, not
> worse)
> 
> "nobody can stop you but yourself" - i can't tell if you're trying to
> make a religious/political statement here, if this is cynicism or if
> you're serious. are you just being defensive or what kind of warning
> is this
> 
> if i hear correctly your main suggestions are
> 
> 1) people should just do whatever they feel like, on their own
> platforms and form new unofficial spaces and not care about how it
> fits in with the rest of the documentation.
> 
> strongly disagree, it seems highly unproductive.
> 
> 2) you say most people are complaining about fqa7
> 
> i haven't heard any specific complaints about that. who exactly was
> complaining about this? where? on this mailinglist?

this is a lot of words about where to post some shit that does not even
exist yet.  nobody needs 'permission' form anyone to do anything.  whence
this sudden craving for bureaucracy?  what is this shit about "power"?
you think owning a domain name is fucking "power" now?  fine, let me
know where to transfer .net and .com.  I'm willing to save ten bucks a
year if it will make you feel powerful.

this whole email of yours is just restating sl's message on the
assumption that he's speaking in bad faith.  it's bullshit, there's no
call for it, and there's no productive possible response to your
questions.  yes, people bitch about the contents of fqa7 on this mailing
list.  they complained in irc too.  what do you intend to do with this
information?  or were the questions rhetorical?

anyway for a long time and in both media they always got the same 
answer: "we know there's room for improvement, please suggest 
improvements." now, it seems, this is insufficent: we must apparently 
elect a project manager for the hypothetical documentation.  or 
something.  I've lost track of what, precisely, you want to happen.

please at least try to remember that the fqa specifically is something
sl created almost entirely by himself.  it's one thing to try to make it
better, but it's another thing to call him an asshole for having done
it.  he's already brooked far more shit about this than I would have, in
his place.

fuck's sake,
khm

Re: [9front] The 9 Documentation Project

[hiro]

sl, it sounds like you're arguing everything should be decentralized
and there should be no hierarchy, and yet the reality is power is
centralized and there is hierarchy and things are enforced (for
example what goes on the 9front website, or the minimum quality policy
for anything that goes into 9front, including the man pages
obviously).

being included on a 9front.org subdomain the fqa is clearly considered
official by visitors.
why do you insist you're some kind of wild rebel if the reality is
that powers have been granted to you specifically. is this somehow
troubling to you?

of course hidden power structures are easier enforced and get
questioned and attacked less often, but i can't beleive that would be
your motivation.

the reason i'm bringing this up is bec. with some alignment (i'm sure
there's enough overlap in goals to allow for this) the end result will
have a higher quality for all of us and we don't have to splinter into
multiple communities that have an even harder time communicating and
collaborating than what is currently the case (there were specific
complaints about this, so i believe we should make it better, not
worse)

"nobody can stop you but yourself" - i can't tell if you're trying to
make a religious/political statement here, if this is cynicism or if
you're serious. are you just being defensive or what kind of warning
is this

if i hear correctly your main suggestions are

1) people should just do whatever they feel like, on their own
platforms and form new unofficial spaces and not care about how it
fits in with the rest of the documentation.

strongly disagree, it seems highly unproductive.

2) you say most people are complaining about fqa7

i haven't heard any specific complaints about that. who exactly was
complaining about this? where? on this mailinglist?

Re: [9front] The 9 Documentation Project

[Michael Misch]

I have no weight nor should you care about my opinion, but what sl just posted was a breath of fresh air

> On Jul 29, 2020, at 8:06 PM, Stanley Lieber <sl@stanleylieber.com> wrote:
> 
> On July 29, 2020 10:14:23 PM EDT, ori@eigenstate.org wrote:
>> 
>>>> I would much prefer thet see
>>>> specific sections of the FQA overhauled in a thoughtful manner, but
>> I
>>>> sure do not have free time for that at the moment.
>>> 
>>> fqa7 needs help.
>> 
>> What in particular do you want help with?
>> 
>>>> "What does this tool do and when do I use it" is a fundamentally
>>>> different question than "how do I operate this tool" and I think
>> mixing
>>>> them in the FQA may be doing a disservice to some segment of the
>>>> readership.  I personally prefer the mixed approach, but I'm not
>>>> everyone.  Yet.
>>> 
>>> i agree we need something like this. i've dabbled with every piece
>>> except assembling a narrative.
>> 
>> I think there are a few different kinds of docs that are
>> worth having.
>> 
>> I mentioned some of this on gridchat, but I'll repeat i
>> here for posteriority.
>> 
>> - Reference manuals. Covering all the options that a
>> program has, as well as describing what it does.
>> This is covered by our manpages.
>> 
>> - Theory of operation documents. These should give an
>> overview of how the parts of the system fit together,
>> and the design considerations that went into it.
>> We've got hints of this in /sys/doc, but it's spotty.
>> 
>> - Tutorials. Hand holding on how to get tasks accomplshed
>> end to end, in detail, explaining both steps and how
>> to do things. This is mostly notes scattered over
>> the web.
>> 
>> - Cheat sheets: Quick references and summaries of how
>> to do things. The FQA, basically.
>> 
>> The divisions are fuzzy -- the synopsis and examples
>> of manpages, for example, also act as a cheat sheet
>> if you already know what you're looking for. But some
>> duplication is fine (and, in fact, good).
>> 
>> As far as most projects go, we're actually in really good
>> shape -- compare to, say, kubernetes, which is basically
>> just a bucket of half-assed examples.
>> 
>> The biggest gaps I see are around some theory of operation
>> documents, as well as some tutorials. I keep referring to
>> /sys/doc/comp.ps as an example of what I'd like, so here's
>> one more mention of it.
>> 
>> And, of course, if people want to look over the manpages
>> and fqa, and submit patches for those: while they're
>> pretty good, that would also be welcome.
> 
> all common complaints are centered on the material covered in fqa7. nobody understands how it all fits together, and we don't attempt to tell them. that seems to be the main problem we're stumbling over here. i agree, it sucks.
> 
> somebody just needs to start writing documents. i don't think any further bureaucracy is required. aside from khm's points that i highlighted above, i really think all the rest is satisfied by, essentially, a central wiki-like-thing of some sort. failing the spontaneous self-organization of an acceptably egalitarian central government, i am happy to link to any extant source of documentation on the fqa. problem solved? and yes, patches to the fqa are always welcome. i may be misremembering, but i don't think i have rejected any pacthes that were sent to me.
> 
> one last point i want to highlight before i throw my phone in the lake: there is some overlap here between calls for a simplified overview document, and a larger, basic disagreement with the style and sensibility in which plan 9 documentation has traditionally been presented. i do think these are separate issues. we do need an overview document. we don't need to cede authority over what ships on the iso to random customers. and really, there is no reason why community documentation needs to be presented under an "official" 9front banner anyway. why is this a sticking point? more than one community wiki already exists. as has been pointed out several times, nobody posts to these things (exceptions duly noted). that's why we don't emphasize them anymore. just create your own documents and make them available. tell me, and i will make sure the fqa points to them. it really is that simple. the way some of this keeps getting revisited makes it seem like  folks are getting very hung up over what is and isn't considered official 9front business. but, why does it matter?
> 
> you know, i never asked permission to create the fqa, either. in point of fact we never asked permission to create 9front.
> 
> nobody can stop you but yourself.
> 
> sl

Re: [9front] The 9 Documentation Project

[Stanley Lieber]

On July 29, 2020 10:14:23 PM EDT, ori@eigenstate.org wrote:
>
>>> I would much prefer thet see
>>> specific sections of the FQA overhauled in a thoughtful manner, but
>I
>>> sure do not have free time for that at the moment.
>> 
>> fqa7 needs help.
>
>What in particular do you want help with?
>
>>> "What does this tool do and when do I use it" is a fundamentally
>>> different question than "how do I operate this tool" and I think
>mixing
>>> them in the FQA may be doing a disservice to some segment of the
>>> readership.  I personally prefer the mixed approach, but I'm not
>>> everyone.  Yet.
>> 
>> i agree we need something like this. i've dabbled with every piece
>> except assembling a narrative.
>
>I think there are a few different kinds of docs that are
>worth having.
>
>I mentioned some of this on gridchat, but I'll repeat i
>here for posteriority.
>
>- Reference manuals. Covering all the options that a
>  program has, as well as describing what it does.
>  This is covered by our manpages.
>
>- Theory of operation documents. These should give an
>  overview of how the parts of the system fit together,
>  and the design considerations that went into it.
>  We've got hints of this in /sys/doc, but it's spotty.
>
>- Tutorials. Hand holding on how to get tasks accomplshed
>  end to end, in detail, explaining both steps and how
>  to do things. This is mostly notes scattered over
>  the web.
>
>- Cheat sheets: Quick references and summaries of how
>  to do things. The FQA, basically.
>
>The divisions are fuzzy -- the synopsis and examples
>of manpages, for example, also act as a cheat sheet
>if you already know what you're looking for. But some
>duplication is fine (and, in fact, good).
>
>As far as most projects go, we're actually in really good
>shape -- compare to, say, kubernetes, which is basically
>just a bucket of half-assed examples.
>
>The biggest gaps I see are around some theory of operation
>documents, as well as some tutorials. I keep referring to
>/sys/doc/comp.ps as an example of what I'd like, so here's
>one more mention of it.
>
>And, of course, if people want to look over the manpages
>and fqa, and submit patches for those: while they're
>pretty good, that would also be welcome.

all common complaints are centered on the material covered in fqa7. nobody understands how it all fits together, and we don't attempt to tell them. that seems to be the main problem we're stumbling over here. i agree, it sucks.

somebody just needs to start writing documents. i don't think any further bureaucracy is required. aside from khm's points that i highlighted above, i really think all the rest is satisfied by, essentially, a central wiki-like-thing of some sort. failing the spontaneous self-organization of an acceptably egalitarian central government, i am happy to link to any extant source of documentation on the fqa. problem solved? and yes, patches to the fqa are always welcome. i may be misremembering, but i don't think i have rejected any pacthes that were sent to me.

one last point i want to highlight before i throw my phone in the lake: there is some overlap here between calls for a simplified overview document, and a larger, basic disagreement with the style and sensibility in which plan 9 documentation has traditionally been presented. i do think these are separate issues. we do need an overview document. we don't need to cede authority over what ships on the iso to random customers. and really, there is no reason why community documentation needs to be presented under an "official" 9front banner anyway. why is this a sticking point? more than one community wiki already exists. as has been pointed out several times, nobody posts to these things (exceptions duly noted). that's why we don't emphasize them anymore. just create your own documents and make them available. tell me, and i will make sure the fqa points to them. it really is that simple. the way some of this keeps getting revisited makes it seem like  folks are getting very hung up over what is and isn't considered official 9front business. but, why does it matter?

you know, i never asked permission to create the fqa, either. in point of fact we never asked permission to create 9front.

nobody can stop you but yourself.

sl

Re: [9front] The 9 Documentation Project

[ori]

>> I would much prefer thet see
>> specific sections of the FQA overhauled in a thoughtful manner, but I
>> sure do not have free time for that at the moment.
> 
> fqa7 needs help.

What in particular do you want help with?

>> "What does this tool do and when do I use it" is a fundamentally
>> different question than "how do I operate this tool" and I think mixing
>> them in the FQA may be doing a disservice to some segment of the
>> readership.  I personally prefer the mixed approach, but I'm not
>> everyone.  Yet.
> 
> i agree we need something like this. i've dabbled with every piece
> except assembling a narrative.

I think there are a few different kinds of docs that are
worth having.

I mentioned some of this on gridchat, but I'll repeat i
here for posteriority.

- Reference manuals. Covering all the options that a
  program has, as well as describing what it does.
  This is covered by our manpages.

- Theory of operation documents. These should give an
  overview of how the parts of the system fit together,
  and the design considerations that went into it.
  We've got hints of this in /sys/doc, but it's spotty.

- Tutorials. Hand holding on how to get tasks accomplshed
  end to end, in detail, explaining both steps and how
  to do things. This is mostly notes scattered over
  the web.

- Cheat sheets: Quick references and summaries of how
  to do things. The FQA, basically.

The divisions are fuzzy -- the synopsis and examples
of manpages, for example, also act as a cheat sheet
if you already know what you're looking for. But some
duplication is fine (and, in fact, good).

As far as most projects go, we're actually in really good
shape -- compare to, say, kubernetes, which is basically
just a bucket of half-assed examples.

The biggest gaps I see are around some theory of operation
documents, as well as some tutorials. I keep referring to
/sys/doc/comp.ps as an example of what I'd like, so here's
one more mention of it.

And, of course, if people want to look over the manpages
and fqa, and submit patches for those: while they're
pretty good, that would also be welcome.