documentation / GSoD & others

[Ivan Mitev]

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

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

I still like the idea of splitting up the "core" and "community" docs.
This would be a good way to:

1. Decrease the review burden on Marek. (He only has to review important
core doc changes.)

2. Make it easier to contribute to the docs (only core docs require our
current Git PR process, which makes sense for high-security and
often more technical core docs). Community docs can have easier
contribution methods, since following them is optional and less
likely to interfere with fundamental security safeguards in Qubes.

3. Decrease the maintenance overhead of the website and docs as a whole.
(The more docs we have, the harder it is to keep everything updated,
organized, and consistent.)

However, I don't think that we should consider this a blocker to GSoD.
Improving the *content* of the documentation is an important goal that
is largely orthogonal to improving our documentation contribution
workflow. We can find temporary ways to make it easier for GSoD
contributors while we work on this workflow issue in parallel. Let's
not allow the perfect to be the enemy of the good.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAly7bCwACgkQ203TvDlQ
MDAa1g/+MfOelQ+YcTHUfhbmoW5IPvDtHSAZEyD72KOnpmxFjzUbtQABeMaqkqm4
br6xqgdA6tZbv4i9GabLsnoQ1EGhOXQInq5JW3LysDqvkVMRt9jKVtZCDopO88+d
KhbwzRt+p9TaCNaIheXhAiSkQqFzL7aLYConVazBQLT+Je0IJhNuI5pfzzHYTAYF
hW6KSq+uT1szVE6IkzFKKLO4Hao0+2/fYG1re510LPPjasX1eJEzifkGP3tB8VVq
bsLx6wZEvxWo7Dcd++x1tZQEuiyHqpLnVebiioQ+/j2G7r7GnUFXvs92V17UZeDi
2o0jRiQQJwdm9XMXC1DQWWaSrWKKEN06LDKiZxAQrBtY1yjCtZY/AOE/fMsmSGGL
cSt3GGsxTxeVypzQ/O1UEzvhq3GNsnE3eCT+doU/72QCWginXAXH0aSHE6DlGx+3
YSLU/+OdWkpYTG/pTiRznuRnnatdmhlAODYORCJjg0jjmSbY+Ihc0vZo4GBfZQlC
E0CbUR+ObJbzs/YKOoKBkDDNm+Vaj7LKCcdsidOZWXcEd2IDo+B9QoIUrM+6Dzz/
qY5Mn4vRGIcV/5ssUwo7cZKhrXXmqXHW1MYFBcuFVQlKkQ7f9+Vw3qyGD4BxFXbM
pyr6SQFSn6alkqPsQ7QIpOHudEySkl5zKy5SFy7wi3cxDC/Dms0=
=kwPw
-----END PGP SIGNATURE-----

[Ivan Mitev]

Indeed. I'd also add:

4. increase visibility of qubes based user projects (eg. by Chris
Laprise, unman, Zrubi, rustybird, ...).

> However, I don't think that we should consider this a blocker to GSoD.
> Improving the *content* of the documentation is an important goal that
> is largely orthogonal to improving our documentation contribution
> workflow. We can find temporary ways to make it easier for GSoD
> contributors while we work on this workflow issue in parallel. Let's
> not allow the perfect to be the enemy of the good.

There are probably only very few "newcomers" with regards to
documentation who are willing to mentor/contribute so it would be a pity
to "loose" some of them because of the issues I mentioned. That's why I
wrote "prerequisite". +1 for making it easier - even temporarily - but
again, IMHO this should be done *upfront*: this could be something as
simple as stating "guys, we'll be working on making the documentation
workflow easier and meanwhile we'll take care of publishing the docs on
your behalf.". As a new contributor I'd find this reassuring as the only
thing I'd have to know is using markdown (and of course writing quality
content). But maybe it's just me.

Side note: I discovered the existence of the qubes-project mailing list
yesterday - not sure how many people are subscribers there compared to
qubes-users (are there public stats?). It is logical that Qubes OS users
are in the best position to write documentation about Qubes OS, so maybe
you should consider posting about GSoD to the qubes-users ML ? And to
increase visibility further more, maybe also add a line to the website
'news & announcement' section ?.
(I don't want to sound like I'm interfering- those are only suggestions,
based on my experience with Qubes OS).

Cheers,
Ivan

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Good suggestions, thanks. I think it makes sense to cross-post the
GSoD message to qubes-users.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAly8s3gACgkQ203TvDlQ
MDAJKQ//ZtE6X9uOluXr30wx11lvdlYcRuBv3WuSttarjqPoSJXpRY64N5yT0Fd6
9EmmdWjFjosjqiROHEWs37UuBrKLXmFb9WNP/nYl0Q80ywOa4ia+Pl90IDSEtAHP
JeDBvtDCmFLovieXRb3Eg2qcEJ+00REyeiaQilS/s6GLOQN2V7Tmg0IbfuO913cT
jnrt+LYDCgs4l4YPJvKTKWNzws/ggaLlvmTpRJzKzcJ9N5Pe7FRu5QxcXLIx/m4r
5C12l3YRlDRKI1cYH4F/zOZm/0P47hKAzpVjaqYrHZsCWGKeB/YkjgWGqdaEADIv
SLv+p3oypnx8m0j83sXsQ7C8EyNZPIkVBrF78UCVFXH3XaK6S0GztaSDMYK3z4FE
H8dd2EyVESs+Cf5uxRSxsK/qxBdFxz45LGWX1J29iWwAJiq586b0tMyhy7kDCcaP
AfS/yD2bIQSasQfSf7KN5MfJiXDApWrqkIHpOseAp9I1BzwCfahyjvLKLUqdPh7Z
F3BWGBPSt4lcrnW5FX6zJjR/7gMZ+vkOfcvGdShGOEfYKKMNZriv1IX8UeafAB9v
YeCx61o0IT0nVp/YI6LF/5IRxpv14VxJxd2WFvyiskS9ilJt2JvEMrsuJ5zqS1+A
CC24jDueg4k0usNRss23aTc2W1seQXgrAqGFfW9toI+MyYWQlIU=
=Or19
-----END PGP SIGNATURE-----

[unman]

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.

[Ivan Mitev]

And yet something seemingly as simple as keeping a forked repository up
to date with upstream - which is probably the next thing a newcomer will
try to fix a few days after forking a repository and seeing "This branch
is X commits behind QubesOS:master" - requires:

(quoting from the official guide at
https://help.github.com/en/articles/syncing-a-fork)

"Fetch the branches and their respective commits from the upstream
repository. Commits to master will be stored in a local branch,
upstream/master".

Hint: re-read the above as someone who has no clue about git and tell me
how you find it hard to believe that people can't get to grips with GitHub.

Before you tell me that I can delete the repo and clone it again: sure,
but it doesn't really seem right. And yes, given the frequency of qubes
doc updates I could also use a stale repository without much chance of
running into a conflicts - but it doesn't seem right either.

The above is not some invented stuff, that's *exactly* my first
experience when trying to contribute doc to Qubes OS. Since I really
like the project and wanted to contribute something back (I already did
financially) I made an effort to learn a new tool that I didn't need -
and still don't - for anything else.

> 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.

Indeed, not many have been left - actually a couple. Nonetheless this
gives a rather negative impression in my opinion.

> 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.

I didn't propose to duplicate material anywhere in my posts so I'm
wondering what gave you this idea. Maybe you're commenting after reading
some docs in the qubes community project. Contrary to what you seem to
think customizing stuff may be easy to do in a normal Arch/Fedora/Debian
install but not so in Qubes OS, or else a document like dpi scaling
wouldn't always be near the top of the popular content hits.

Anyway it looks like I'm a minority thinking that the process could be
improved, or seeing issues that don't exist, so I will refrain from
posting anymore about documentation topics.

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

It's true that the vast majority of "limbo" PRs are ones where we're
waiting for the contributor to respond. I made a conscious decision to
leave these open for a long time, because contributors are volunteers
who should be able to respond at their leisure, but I can start
closing the oldest ones with a message that makes it clear that they
can be reopened.

>> 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.
>
> I didn't propose to duplicate material anywhere in my posts so I'm
> wondering what gave you this idea. Maybe you're commenting after reading
> some docs in the qubes community project. Contrary to what you seem to
> think customizing stuff may be easy to do in a normal Arch/Fedora/Debian
> install but not so in Qubes OS, or else a document like dpi scaling
> wouldn't always be near the top of the popular content hits.
>

I think unman is responding to the point that "some of the docs aren't
specific to Qubes OS" by saying that we shouldn't even have such
documents. I agree insofar as it doesn't make sense for us to write
and maintain documentation about non-Qubes stuff when we still have so
much work to do writing and maintaining Qubes documentation.

However, your point that "customizing stuff may be easy to do in a
normal Arch/Fedora/Debian install but not so in Qubes OS" indicates
that *those* particular documents *are* Qubes-specific, so they (or at
least the Qubes-specific parts of them) should stay. (We can work out
whether they should be community or core.)

> Anyway it looks like I'm a minority thinking that the process could be
> improved, or seeing issues that don't exist, so I will refrain from
> posting anymore about documentation topics.
>

I think unman was just offering his opinion, not suggesting that you
should stop posting about documentation topics.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAly/83EACgkQ203TvDlQ
MDDY0BAAzAqYYjr/wU56/r2Os8mo3C+8opRXdw/sSNWzr0S+MnoKnFbG2OB6CHdt
7onggqvJMYZ7n5Gi3wAbb0uhBOJzwfHBag6lSwlzDdTA2CYcOQh+XNALVq8lzcnx
eOt837vsDv/PJK2v4oLxF0KJF884vC9TXFfgWJ82s9cU2MoLEjQlrt0YKCdUpYoL
yioC4vZvSqjOMdP8zKn2yLmA+NHsdpf7IXilLRZo9XX/hsy5PzGorxNt1LqzvmDd
haWXPegtHGUIybkyDnTM3ZVdt22+SjSjR7K1lfJ3BDy2cQCxbU5+HvfRjk0RF+Xl
rTXW1xXYWTp2rh1Comz/xNA6pMdfz2yBO8kD02PUeJHrezITyhgxgJkOvHuf/6w4
Mff3Xhz//ArQd9hGKMGviSnrDZunjib9LPrBjIhy59CMUBSBw1UmVN/ET1J9iGUM
G+Hp/np2lPXDWdRtN3wQ28t/Qsgn0+jNPDQ8rAJ6M3BjIGLlne3i1GsVNXlQSuur
tV8y2WAa4Rov42OdvxF0cE1Ct6AnZYS46RH9mjZcI5z7nVHqvCHxpRH/2SK6obTx
83ZS6na6+H0/XYPRWOB+GRin5hl9OMFFmY6HUX1sMLQ7RYTlNmyInwyZnVy1jIfO
ZZDYvM3LJEOcbPk3jgXDVDA/UlDKj5rXZxOoNYNr7aa+3yv9DVA=
=GQ5A
-----END PGP SIGNATURE-----

[unman]

On Wed, Apr 24, 2019 at 12:26:18AM -0500, Andrew David Wong wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA512
>
> On 23/04/2019 3.34 PM, Ivan Mitev wrote:
> > Anyway it looks like I'm a minority thinking that the process could be
> > improved, or seeing issues that don't exist, so I will refrain from
> > posting anymore about documentation topics.
> >
>
> I think unman was just offering his opinion, not suggesting that you
> should stop posting about documentation topics.
>

Yes.
Ivan, please dont be discouraged by my shortness.
I would hate for you to stop posting on this or any other subject.
Please accept my apologies.

unman