On Sat, Apr 20, 2019 at 06:45:04PM +0300, Ivan Mitev wrote: > 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 >
I find it hard to believe that people cant get to grips with GitHub: you dont need to understand git to edit docs in the GUI interface. Most of the "limbo" docs seem to be where the OP has disappeared or failed to follow up on suggested edits. I dont think many have been left otherwise. Yes, we should cull some of these or just re-edit to close. I dont think that Qubes should duplicate material widely available elsewhere, whether on security matters or not. Maybe there should be a prominent note explaining that in *many* cases, templates act just like normal Arch/Fedora/Debian and installation/problem solving should be treated accordingly. -- 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 [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/20190423120623.rzwkqrgovui33qlh%40thirdeyesecurity.org. For more options, visit https://groups.google.com/d/optout.
