[9fans] Improving Plan 9 Documentation

[9fans] Improving Plan 9 Documentation

[kalona.ayeliski]

[-- Attachment #1: Type: text/plain, Size: 3756 bytes --]

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? 


Standard Operating Procedure (SOP) for Administering Venti Mirroring on Plan 9

1. Purpose
- Objective: To provide a clear, step-by-step guide for administering Venti mirroring on a Plan 9 system.
- Scope: This SOP applies to all system administrators and users responsible for maintaining Venti storage on Plan 9.

2. Definitions
- Venti: A network storage system that stores blocks of data identified by their content.
- Mirroring: The process of duplicating data from one Venti server to another to ensure data redundancy and availability.

3. Prerequisites
- Required Knowledge: Familiarity with Plan 9 commands, Venti configuration, and basic network administration.
- Necessary Tools: Plan 9 system, access to Venti servers, network connectivity.

4. Responsibilities
- System Administrator: Ensure the Venti mirroring process is correctly set up, monitored, and maintained.
- Users: Report any issues or discrepancies found during the use of mirrored Venti storage.

5. Procedures
5.1 Initial Setup
1. Access Venti Configuration: Log into the Plan 9 system and access the Venti configuration files.
2. Configure Primary Venti Server:
   - Edit configuration to enable mirroring.
   - Set up network parameters.
3. Configure Secondary Venti Server:
   - Ensure it has identical storage capacity and configuration settings as the primary server.

5.2 Establish Mirroring
1. Synchronization:
   - Run initial data synchronization between primary and secondary servers.
   - Verify data integrity post-synchronization.
2. Automate Mirroring:
   - Set up automated scripts to handle periodic synchronization.
   - Schedule regular intervals for mirroring.

5.3 Monitoring and Maintenance
1. Monitor Logs:
   - Regularly check logs on both primary and secondary servers.
   - Look for synchronization errors or network issues.
2. Perform Routine Checks:
   - Ensure data consistency between servers.
   - Validate the integrity of mirrored data periodically.
3. Troubleshooting:
   - Address synchronization failures promptly.
   - Resolve any discrepancies between mirrored data sets.

6. Documentation
- Logs: Maintain detailed logs of all synchronization activities.
- Reports: Generate periodic reports on the status of Venti mirroring.

7. References
- Plan 9 Documentation: Refer to official Plan 9 documentation for detailed commands and configurations.
- Community Forums: Engage with 9fans for additional support and troubleshooting tips.

8. Review and Updates
- Review Frequency: This SOP should be reviewed annually.
- Update Procedure: Amendments to the SOP must be approved by the system administration team.


--Chris Childers (aka Kalona Ayeliski)
------------------------------------------
9fans: 9fans
Permalink: https://9fans.topicbox.com/groups/9fans/T3bed924e432ee795-Maa1e4baf4847ec87eaaf64a1
Delivery options: https://9fans.topicbox.com/groups/9fans/subscription

[-- Attachment #2: Type: text/html, Size: 5458 bytes --]

Re: [9fans] Improving Plan 9 Documentation

[sirjofri]

Hi,

03.08.2024 22:38:47 kalona.ayeliski@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

Re: [9fans] Improving Plan 9 Documentation

[kalona.ayeliski]

[-- Attachment #1: Type: text/plain, Size: 463 bytes --]

The annual review is solely for my use. I organize recurring tasks with a monthly tickler system based on their frequency. You are right; it may not be suitable for community practice. Many of my ideas and practices are unconventional.
------------------------------------------
9fans: 9fans
Permalink: https://9fans.topicbox.com/groups/9fans/T3bed924e432ee795-M6a7ad625dd5ded6f606d1c45
Delivery options: https://9fans.topicbox.com/groups/9fans/subscription

[-- Attachment #2: Type: text/html, Size: 957 bytes --]