I recently suggested many documentation updates and the conversation is beginning to look quite caotic.
Why handling docs updates on a forum is a bad design choice?
- the conversation becomes very long and makes it hard to track changes (each new answer makes the subsequent patch at least
lis the current length of the discussion)
- if two or more users submit a patch, then the answer of the maintainer is detached from the question (you can check the reply, but it’s not very intuitive, especially if the conversation on such issue has many questions and answers)
- if a patch has already been submitted, but not yet committed, someone coming to the page has hard time finding that, and would possibly duplicate the effort
- whenever you want to submit a patch, you need to make a vague description like “I mean the part where it says
command X, Y, but the second time, not the first, the first is fine”
- the maintainer needs to figure where the patch applies and then do some copy/paste job, which is very error-prone
- the fact that all of the previous points make the work harder discourages contributing
My recommendation is to have the documentation being a collection of markdown files in a GitHub repo
Advantages of a
docs.md GitHub repo:
- each conversation pertains to a single patch or issue
- because of 1, it scales horizontally, so patching has always the same difficulty regardless of the previous submissions
- when you send a patch, an automatic diff is generated and it’s clear where the issue lies and where your contribution is going
- the maintainer can eventually accept the contribution, if deemed acceptable, and it
- considering the audience of snap software, most if not all have already a GitHub account, and GH is their primary mean to contribute to some snap or to third party projects, so they need extra effort to contribute to a docs forum and register to a separate platform
- it’s already a common practice in many other projects, so embracing it has a much lower effort than changing method
An example of how the end result would look like
This is an example from a course I’m following, and to which I enjoyed contributing.
Example page: https://fullstackopen.com/en/part0/general_info
Same page on GH for contributions: https://github.com/fullstack-hy2020/fullstack-hy2020.github.io/edit/source/src/content/0/en/part0a.md
Note how all content pages have a Propose changes to material-button that links easily to the given page, similarly to how it works here with the docs.
The process of contributing to that project is very light and enjoyable, while contributing to snap and snapcraft on the contrary is much more painful, and there is no reason it needs to be like that
A shared frustration
Many people have risen such issues in the past, please, listen to your community (which can likely include clients), this is of mutual benefit.
We are sharing our frustration because we really like the technology and the concept of snaps, and would likely this to succeed, but this becomes much harder if we cannot work properly