Sigh. You’re really going to make me copy/paste from the link, aren’t you? “The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes.”
Think of the Qubes OS Project as making the engine for your car or the CPU for your personal computer. They write technical manuals for those artifacts, but those technical manuals are meant to be consumed by other technical people, not by non-technical end users. The manual for an engine is not the manual for a car. A CPU spec sheet is not a personal computer manual. Someone further down the chain, closer to the non-technical end user, is responsible for making things easy to use for consumers. If we had enough resources to vertically integrate this supply chain, we could do it all ourselves, but we don’t. The core documentation is largely a volunteer effort and is barely sustainable in its current state.
And your post isn’t? Hint: Everyone else’s text is a “wall” when you don’t like what it says or don’t feel like reading it (but never your own).
That page is part of the developer documentation, and it’s about contributing to the documentation. It’s not for end users who are merely using Qubes. If you’re contributing to the documentation, “thinking” should be a prerequisite.
Do you think we don’t understand that users don’t want to have to think? That things should “just work”? Have you considered the possibility that we understand and share that goal but that the reality of the situation has led us to what you currently see?
Don’t wish it. Write it!
A worthy goal. Make it happen!
“Many contributors do not realize that the there is a significant amount of work involved in maintaining documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to go through a review process to ensure accuracy before being merged (see security), which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It’s also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.”
So, the key questions are: Who’s going to help maintain it, and for how long? Usually people get all excited about writing a new piece of documentation, submit it, then promptly forget about it and move on with their lives. It then becomes my job to take care of it for eternity, and as these all pile up, it’s just not sustainable. Look, if this new guide is as good as you say, then we’ll be happy to have it as part of the official docs for as long as it gets maintained. But if the maintenance burden becomes untenable, we’ll have to triage it, like we just did with the community doc migration.
I think it would be more useful to leave it on this forum than to publish it on its own website, unless that other website is the existing Qubes Community website. (Might even be worth considering merging Qubes Community into a guide/wiki section of this forum.) Let me be clear: A lot of people complain about the Qubes documentation, but not many people are willing to lift a finger to do anything about it. Those people should be the change they want to see in the world. Everyone should follow Sven’s lead here and help write the documentation that you think is missing or bad, and if you can’t write it yourself, persuade others to help you.