Hi, 03.08.2024 22:38:47 kalona.ayeli...@fastmail.us: > This is a follow up from another thread. Here is a revised template. I > removed the contested commands and kept the procedure generic to express an > idea for improving documentation. I share this in hopes of fostering better > ideas for enhancing Plan 9 documentation. > > It was suggested that we create blogs and post our work for others to find. > However, I find this idea flawed, as it has not been conducive to feedback > and the development of comprehensive reference documentation. A more > effective method would be to create standardized documentation on a community > wiki, in my humble opinion. > > Improving documentation is a community effort. I simply want to propose an > idea. What are your thoughts on improving documentation? What areas would you > like to see improved?
I glanced through it and it seems to be much better than anything you posted before. It doesn't contain that much useful information, but it can serve as a first outline for a collection of documents. I'd say, if you can fill it (and others will probably help), the structure can be adjusted as you (all) go. As you said, it's a community effort. I have some issues with one point you mentioned (not content, but organizational). You can surely say that the documentation should be reviewed annually, but that sounds like a request. Since nobody gets money for it, it is a weird request. It's fine for a corporation, but a community usually works a bit differently (also considering that we are a small community). Another big question (also for collaboration) is, where do you store it. For 9front, there's a semi-public repository with wiki pages, the fqa and the man pages also accept patches which are discussed (like usual) on the mailing list. Plan 9 originally has a wikifs, some are still publicly readable, at least. It would be possible to revive that somewhere and extend it with additional pages, which also happened (9p.io). However, there's basically no discussion about the wikifs pages as far as I know. An additional discussion page could be helpful. Btw, I'm also considering rewriting/adjusting wikifs as compatible as possible, but with markdown syntax and git for versioning. Compatibility will mostly be for the acme Wiki reader/writer and the web filesystem, though the web pages will look different (and maybe be adjustable). I haven't started that project yet, but I personally want to use wikifs (or that replacement) more in the future, also for (non-plan9) software documentation. Regarding blogs, it's quite common in this community to share self-contained details in blogs. This is not ideal, but it is what it is. Some things should imho end up in some /sys/doc kind of place (but without bloating that place), maybe iwp9 could provide something? It's not that easy though, because there are some aspects regarding quality etc. (I don't want an International Workshop on Plan 9 Documentation, that would be too much and the format wouldn't be fitting for an agile part such as documentation). Please, whenever contributing anything to the community that's AI generated, keep looking at it with your own eyes and revising it. I personally want to read it as something you put work and thought into it, not as blabbering of a statistical parrot. The quality of your structure is on a totally different level than in the previous posts that just contained wrong information. Content-wise I can't really verify that everything is correct or makes sense, because (1) I only glanced through it and (2) I basically know nothing about venti, especially compared to people who are using it (like Charles) or who studied it (like Noam). That said, I can only talk as someone who just loves good documentation and who also loves to document. (That's also one reason why this mail is so long, so please forgive me). There are also a few more things to say, but this mail is long enough. If you want, you can email me off-list and I can tell a bit more. sirjofri P.S. also regarding LLM content: consider that people can always ask ChatGPT themselves. LLMs are largely available, and people can use it as a tool as they wish. ------------------------------------------ 9fans: 9fans Permalink: https://9fans.topicbox.com/groups/9fans/T3bed924e432ee795-M60054309d757db02c54c946d Delivery options: https://9fans.topicbox.com/groups/9fans/subscription
