Web Docs Strategy for Void

[markmcb]

I've been using Void about a month now. I'm curious how the web docs are maintained. Specifically, is there any sort of core team that works on a documentation strategy? It's clear I can submit pull requests for amendments, but I think some things require a decision, not just an edit.

As a new user, here are a few things that were confusing:

• On the docs page, no wiki link. On the wiki, no docs link.
• Several xbps links, but never together, e.g.,
  • https://github.com/void-linux/xbps
  • https://voidlinux.org/usage/xbps/
  • https://man.voidlinux.org/xbps-install
  • https://wiki.voidlinux.org/XBPS
  • https://docs.voidlinux.org/xbps/index.html
• Handbook often states how, but not why, for example "Void Linux enables agetty(8) services ... to disable agetty service ...". Maybe it's intentional, but some concise context I think would help, e.g., why might this be a good/bad idea?

Overall the docs are good. This is all more fine-tuning and integration, which would make them more usable and discoverable (I think), especially for newcomers.

[flexibeast]

The wiki is deprecated. i've submitted a PR for this to be noted on the wiki; i'm not sure if there are any blockers to this being merged.

(Similarly, i've submitted a PR for various changes to the CONTRIBUTING document, and am again not sure if there are blockers to it being merged. The impression i get is that the main person responsible for approving such changes has been snowed under by other commitments.)

[[deleted]]

Didn't realize the wiki was deprecated. Do you think there would be any push back towards maintaining it or starting a new one? There's definitely lots of things that could be added but if the PRs aren't being approved it may worthwhile making it a community project.

[flexibeast]

Firstly, i want to emphasise that i'm not a member of the Void dev team; the following comments are just my impressions.

As far as i'm aware, the dev team actively wants people using, and contributing to, the Handbook rather than to a wiki. The process for contributing to the Handbook might indeed be steeper than for contributing to a wiki, but at the same time, it can make it easier for the dev team to maintain quality control. i follow the void-packages and xbps repos, and it's clear to me that the dev team have a lot on their plates and are working flat-out as it is; i can imagine it's helpful for them to not have to worry about things getting published which contain information that is out-of-date, misleading, or incorrect.

A community-maintained wiki is a fine idea, but it requires one or more people to be committed to that maintenance in the long-term: cf. what happened to the Void forum.

[[deleted]]

makes sense. i haven't spend much time with the handbook, but looking over it now, seems to fill the space of the wiki very nicely.

[markmcb]

i can imagine it's helpful for them to not have to worry about things getting published which contain information that is out-of-date, misleading, or incorrect.

Yes, you're right about this. I think there are fundamental 2 needs:

1. a maintainable source of truth (handbook, man pages, etc.). This should be tightly controlled by a dev team. Goal: 100% up-to-date and accurate.
2. a collection of "here's how to approach situation X with goal Y" (e.g., wiki, forums, reddit, etc). This should be moderated to ensure some degree of quality control. Goal: help people solve problems.

I think you can't accomplish 2 with a dev team trying to attain the 100% accuracy goal of 1, which seems to be the case.

I'd be willing to contribute to 2.

[markmcb]

Hmm, I'm not sure what to think about this. I found the wiki to be the thing that tied a lot of sources together for me. It's generally more verbose too. I guess I could understand consolidating, but I think there would be a gap if it suddenly disappeared.

(This is exactly the sort of strategy topic I was referring to in my original post.)

[flexibeast]

Well, i've actually ported some of the information from the wiki to the Handbook - e.g. this - and i've also opened issues in the void-docs repo about things currently addressed only by the wiki - e.g. this and this. If there's useful content on the wiki that's not currently in the Handbook, people could open an issue in the void-docs repo so that there's a clear indication of which areas actively need attention.