re- "Google "Season of Docs" -- deadline April 22" [new post to avoid polluting the original one that is linked to in the gsod web page.]
I thought about posting about GSoD back in January but in my opinion making documentation easier to contribute should be a prerequisite to finding cool topics and motivated people. Having spent a significant amount of time trying to improve documentation, those are the areas where I see some room for improvement: 1- don't assume that people are comfortable with git or that it's easy to update the docs in github. It most likely puts off people who would have otherwise contributed to the documentation. Despite Qubes OS' tech-savvy audience it shouldn't be expected that users are developers and/or power users who most likely know git (@qubes-users is filled with questions that show this isn't the case). I'm also probably not the only "advanced" user out here who don't know git (actually, 'didn't', because I learned the basics *only* to be able to contribute docs and I still find it awkward to use and forget about commands). Ref.: [1] [2]. There are a few solutions to this that have been proposed - wiki, "staging" area, helping users, etc., but nothing official. 2- keeping PRs in limbo when people have spent time trying to contribute doesn't reflect well on the project [3] (obviously, not all the PRs in the queue are applicable). 3- strongly related to the issue above, decreasing Marek's workload should be a priority. Given the trust that users put into Qubes OS it is expected that the docs' instructions are (reasonably) safe to use, which in turn requires someone with expertise to review the docs. But: * is Marek the only qualified person out here to review those docs ? (genuine question, I'm not implying there is someone else). * some of the docs aren't specific to Qubes OS, and/or don't really require a thorough security review; those could be reviewed by knowledgeable Qubes OS users. I suggested splitting the documentation between "core" docs and "community" docs weeks ago [4] (when I had some spare time and could have helped) but while the issue got an initial positive comment by Andrew it hasn't gathered any interest since then (to be fair Andrew hinted back at the issue recently [5]). So - it'd be nice to know what you guys think. 1- is clearly contentious: unman and Andrew stated they didn't see any issue but other people disagree. 2- and 3- are correlated and it'd be helpful to know if something will change in this area: this will for instance determinate the fate of some of the docs written for the Qubes Community project (either they'd stay there, move to another "community" project, or someone would try to submit them to the official docs). Note: the views I've expressed are mine only and may not be shared by the other folks over at the Qubes Community project. Ivan [1] https://groups.google.com/d/msg/qubes-devel/wxistC0_FHo/_F_4l1_oCQAJ [2] https://github.com/QubesOS/qubes-issues/issues/3629 [3] https://github.com/QubesOS/qubes-doc/pulls [4] https://github.com/QubesOS/qubes-issues/issues/4693 [5] https://github.com/QubesOS/qubes-doc/pull/811#discussion_r273760337 -- You received this message because you are subscribed to the Google Groups "qubes-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-devel+unsubscr...@googlegroups.com. To post to this group, send email to qubes-devel@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/82654bcc-d5e4-d061-d76b-4f46f6088e7b%40maa.bz. For more options, visit https://groups.google.com/d/optout.
