Cleaning up the documentation - preferred way of dealing with historical releases

[aronowski]

I'm currently in the process of reading all the docs and wanted to clean up. There are several mentions of historical releases like 4.0 or even 3.2, like here.
The question is: what should I do with them?

1. Leave them as-is since there's a mention, for which release they were meant?
2. Remove them entirely since anyone interested can just go back in time with Git and read them?
3. Make a 'legacy versions' section, where they will be moved?
4. Something else?

[ghost]

Good question. The community docs (try to) follow the official docs' guidelines (in the "Release-specific documentation" section).

Official issue 5308 tracks changes to the current guidelines to move to a release-based documentation (which IMO is the best approach). However it takes a lot of resources - that this project doesn't have - to review/approve old docs.

As a side note it seems there's also a push to investigate migrating to readthedocs (in this project's case this would make it easier for people to find resources - questions in the forum show that people aren't all aware of this project).

That said, for now we should probably stick to having different sections for each main release as per the official guidelines. If there isn't a section for the current release, we could either create one based on instructions from the older version if the instructions need to be updated/fixed, or if the instructions are identical, simply add a leading comment with "the following instructions are known to work on releases X, Y, Z").

[aronowski]

Thank you for the information.
As an example, I made this PR where I hopefully got the style right. If this is appropriate, I'll stick to it for the rest of the documentation refactoring process.

[ghost]

Hey!
I've looked at each commit in your PR, everything looked OK, I'd have refactored the doc the same way you did so I've merged the PR. That said, @andrewdavidwong, @awokd : any comment before @aronowski potentially spends time refactoring other docs ?

[andrewdavidwong]

Official issue 5308 tracks changes to the current guidelines to move to a release-based documentation (which IMO is the best approach). However it takes a lot of resources - that this project doesn't have - to review/approve old docs.

As a side note it seems there's also a push to investigate migrating to readthedocs (in this project's case this would make it easier for people to find resources - questions in the forum show that people aren't all aware of this project).

The QubesOS/qubes-issues#5308 push toward release-specific docs has actually been completely taken over by the migration to Read the Docs. I think this is the main thread about it right now:

https://groups.google.com/g/qubes-devel/c/ASj7tehn1G0/m/fA33ylhHAgAJ

[ghost]

Apologies for my reply's delay.

@andrewdavidwong : I've been following the thread you mentioned over the past months - that's why I'm wondering what might be the impact on the docs here. I have zero experience with RST, readthedocs, sphinx and whatnot - and to be frank not much time to investigate those atm. - so it'd be nice to agree on what to do before our contributors spend time reformatting doc and then potentially spend time for another round of reformatting. IMO:

• if you think RST/readthedocs/... is super easy then it'd be better to "mirror" the official docs' guidelines and move to RST/...
• if not, we'd stick with the old - but still current - guidelines ; ie. a section per release in this specific case. Optionally we could make the index page better.

Thoughts ?

[andrewdavidwong]

I have zero experience with RST, readthedocs, sphinx and whatnot - and to be frank not much time to investigate those atm. - so it'd be nice to agree on what to do before our contributors spend time reformatting doc and then potentially spend time for another round of reformatting. IMO:

• if you think RST/readthedocs/... is super easy then it'd be better to "mirror" the official docs' guidelines and move to RST/...

I don't have any first-hand experience with it either yet. @maiska is the primary person who's been working on it and would be the one to ask.

[ghost]

I don't have any first-hand experience with it either yet.

Ah, we're in the same boat then :)

Hopefully @maiska will chime in with some info then...

[maiska]

Hello @taradiddles would love to help!
I do not know what is the objective here, besides cleaning up (even that I do not know what it entails).
If you want to clean up with the goal to converting to rst, this would be a blast imho.
RST/RTD bottomline (in my experience) - the conversion is a b****, but overall rst/rtd/sphinx is pretty slick and easy to use, once you get around it, read some basic guides and play around.
What can I do?

[ghost]

I do not know what is the objective here, besides cleaning up (even that I do not know what it entails).

There isn't much of a goal yet :)

"cleaning up" meant reviewing the docs to remove old, unsupported stuff and reformat the docs - the OP's question was how to deal with releases (eg. one section per release with potentially a lot of duplication) - ie. the same issues that the official docs move to RST/RTD would address. This project's guidelines try to track the official ones - so if the official doc change it would seem to be a good idea to migrate too - or at least investigate it. From what I've read in the related issue and mailing list thread, this would:

• (kind of) solve the problem of having stale/deprecated doc and solve the "one section per release" question (which was the OP's question). The "vetting" process of old pages might be too much of a workload though - there's very much the possibility that nobody takes care of reviewing old pages to see if they're still relevant/OK for the latest release.
• hopefully provide more visibility. Forum posts have shown that people often aren't aware of this project. I just did a search with "qubes os http filtering proxy" and it returns nothing related to this project, despite the index having a closely related entry ("Make an HTTP Filtering Proxy"). It could be because this readme/index isn't in the project's root (we could try to move it to /) - but it could also be because of the way search engines index such readmes. If it's the latter, having the docs on readthedocs.io might be more visible.

So - since we(/I) know nothing about RST/RTD and the ongoing migration of the official docs I was interested to hear your opinion on:

• the initial conversion; I understand from your reply that it isn't straightforward but since it'd be done once it could be OK.
• ongoing maintenance ; we're running on limited resources here so there shouldn't be an additional recurrent workload to manage the infrastructure. Does readthedocs.io provide everything eg. like github does ? Or are there maintenance scripts/stuff that need to be run/done on external servers and "pushed" to rtd ?
• how easy it is to intuitively write RST docs coming from markdown. I had a quick look at RST - it looks intuitive ; however I'm concerned that migrating to RST could be something that prevents the small number of contributors we have from contributing (even updating their own docs once the format has changed) as it's yet-another-thing-to-learn. The "reverse" issue is that in the long run, we'd have the opposite problem: using markdown while the official docs use RST, preventing people knowing only one or the other from contributing to either project (one of the ideas of this project was to have "looser", but similar guidelines in the hope that contributors would then be confident/knowledgeable enough to contribute to the official docs).

Lastly - I haven't closely tracked the ml thread - any idea when the migration may happen with the official docs ?

Thank you in advance for your input !

[maiska]

"cleaning up" meant reviewing the docs to remove old, unsupported stuff and reformat the docs - the OP's question was how to deal with releases (eg. one section per release with potentially a lot of duplication) - ie. the same issues that the official docs move to RST/RTD would address. This project's guidelines try to track the official ones - so if the official doc change it would seem to be a good idea to migrate too - or at least investigate it. From what I've read in the related issue and mailing list thread, this would:

* (kind of) solve the problem of having stale/deprecated doc and solve the "one section per release" question (which was the OP's question). The "vetting" process of old pages might be too much of a workload though - there's very much the possibility that nobody takes care of reviewing old pages to see if they're still relevant/OK for the latest release.

yes, RTD supports different versioning of the documentation, which would solve this problem and still have a clear cut between different versions. it can be easily done

* hopefully provide more visibility. Forum posts have shown that people often aren't aware of this project. I just did a search with "qubes os http filtering proxy" and it returns nothing related to this project, despite the [index](https://github.com/Qubes-Community/Contents/blob/master/docs/README.md) having a closely related entry ("Make an HTTP Filtering Proxy"). It could be because this readme/index isn't in the project's root (we could try to move it to /) - but it could also be because of the way search engines index such readmes. If it's the latter, having the docs on readthedocs.io might be more visible.

There is also a dedicated guide for SEO optimization for RTD, see here: https://docs.readthedocs.io/en/stable/guides/technical-docs-seo-guide.html so I think this would also solve that problem

So - since we(/I) know nothing about RST/RTD and the ongoing migration of the official docs I was interested to hear your opinion on:

* the initial conversion; I understand from your reply that it isn't straightforward but since it'd be done once it could be OK.

That is correct. By difficulties I mean handling cross-referencing links. That's the big hurdle. Otherwise, using pandoc you can easily straigthforward convert from github markdown to rst in a second.
As I see from the community docs repo you refer to other documents not via the url but relative path, which should take extra handling to declare the links either as a doc role (for a ref to a whole doc) or as a ref role (for a ref to a section inside another doc f.ex.)

* ongoing maintenance ; we're running on limited resources here so there shouldn't be an additional recurrent workload to manage the infrastructure. Does readthedocs.io provide everything eg. like github does ? Or are there maintenance scripts/stuff that need to be run/done on external servers and "pushed" to rtd ?

RTD provides everything. Take a look at the repo here https://github.com/maiska/qubes-rst. This is actually more or less what you need to deploy on RTD. The files of interests in this case are .readthedocs.yml and conf.py. Here is a simple straighforward sample tutorial you can check out also: https://docs.readthedocs.io/en/stable/tutorial/index.html

* how easy it is to intuitively write RST docs coming from markdown. I had a quick look at RST - it looks intuitive ; however I'm concerned that migrating to RST could be something that prevents the small number of contributors we have from contributing (even updating their own docs once the format has changed) as it's yet-another-thing-to-learn. The "reverse" issue is that in the long run, we'd have the opposite problem: using markdown while the official docs use RST, preventing people knowing only one or the other from contributing to either project (one of the ideas of this project was to have "looser", but similar guidelines in the hope that contributors would then be confident/knowledgeable enough to contribute to the official docs).

I would say it is easy. There is some more complicated syntax when using doc and ref roles, particularly if you have a emphasized portion of a section's title for example, but it is not something one cannot master, and imho if explained in a simple manner should not be a lot to handle. Bottomline is imho, the writers of the documentation are users of Qubes OS which comes with its own learning curve, so I think that should not be a problem. But yeah, I get the concern

Lastly - I haven't closely tracked the ml thread - any idea when the migration may happen with the official docs ?

That should be a question for @marmarek I think :)

Thank you in advance for your input !

Sure, no prob. If you want I can help with conversion, once the conversion of the official Qubes OS is done, since I now dream of docutils and rst unfortunately and have an idea how we can tweak the python tool to take into account the pecularities of the community docs repo - in specific take the folder structure as a basis for cross referencing.

And of course what could be also fine in the future would be making localization of the community docs also a reality in one way or another :)

If I missed something please say so so I can clarify if needed

[ghost]

Thank you @maiska. I'll have to dig the topic further but I have a much better idea how this might work now.

I'll try to do some tests when I have a bit more time, but in hindsight the question that's probably most relevant is "how much more work would RST/RTD be for a contributor compared to the current markdown/github setup". As already mentioned the main concern is that with we should really not raise the technical bar (which is already quite high IMO - that's maybe one reason why people just publish free-form guides on the forum rather than bother forking a repo, sending a PR, etc.).

For instance I'm wondering how easy it would be for people to preview their contribution before sending a PR: a quick web search indicates that github doesn't interpret RST, yet .rst files are shown as html - kind of: at first glance attached pictures don't show up and some formatting isn't processed/translated (eg. :doc:). In comparison, markdown is pretty much "wysiwyg".
Note that I'm comparing Qubes OS docs (eg. the md, rst and rendered versions of "how to organize your qubes") - maybe pictures would show up in both the md and rst version if they were hosted in the same repo. But either way the rst doc on github doesn't look as good as the markdown's equivalent.
tl;dr; my concern is that there shouldn't be the need of back-and-forth between PR -> RTD rebuild -> noticing something's wrong (say - with links) -> new PR -> etc.

Sure, no prob. If you want I can help with conversion, once the conversion of the official Qubes OS is done, since I now dream of docutils and rst unfortunately and have an idea how we can tweak the python tool to take into account the pecularities of the community docs repo - in specific take the folder structure as a basis for cross referencing.

Thanks - we'll definitely need a hand if we move to rst/rtd :-)

And of course what could be also fine in the future would be making localization of the community docs also a reality in one way or another :)

Indeed

[maiska]

Hello @taradiddles,

yes, I understand what the problem is. Perhaps github actions could be a possible solution? There is already one I found for build but for viewing (so that the contributor does not have to go over to RTD, though this would be the better solution imho) I have not, apart from deploying on gh-pages. I have not tested these though.

For viewing: if a contributor writes the documentation locally first (which is the way to go imho for more than a word/ simple sentence change) you can view it using sphinx-view . -c conf.py (f.ex.). An explicit guide about that could be helpful. So that just the final build must be made

About the forum: a rst/md template would be nice, but as far as I searched such a plugin is not available and one should write it themselves, which yeah... Perhaps a friendly reminder when somebody posts on the forum that one could contribute to the documentation with a link to the official and the community ones could be an easy to go solution at first?

I'll get back to you here if I have found something worth exploring to ease up the contribution to the community docs as mentioned in the first paragraph.

Yep, would love to help out either way!

[ghost]

Thank you for your input !

Perhaps github actions could be a possible solution? There is already one I found for build but for viewing

you can view it using sphinx-view . -c conf.py

OK - so that's adding another step to the contribution process. That said it's not like rst previewing in github is that bad, and locally both markdown and rst need something to be rendered properly (pandoc, vim/emacs with syntax highlighting, ...).

So - it's not clear cut. One goal of this project was to mirror the official docs' process/infrastructure, which would mean migrating to rst too; but other prominent goals were to provide a staging ground and lower the bar for potential contributors - meaning we'd probably be better off sticking to what we currently have, optionally re-organizing the index (+ moving it to /) to have better search engine results.
@awokd, @andrewdavidwong - thoughts ? Personally I'm leaning towards the latter, and then we could revisit this later on but if you guys prefer rst/rtd I'm of course OK.

[andrewdavidwong]

Hm, not sure which would be the best way to go. You might consider asking frequent (or would-be) contributors on the forum and/or mailing list. Maybe make a poll?

[ghost]

@aronowski - It took quite a bit more time than expected to get back to your original question - sorry about that.

The bulk of the reviewing work is verifying that instructions are applicable to the current Qubes OS version. We'd have to do that process anyway with RST/RTD - so in case we migrate to RST/RTD someday there won't be much to do other than splitting community docs into several release-specific docs.

If you're still interested to help (no worries if other things have taken over!), given what we've discussed in this whole discussion the best approach would be to have instructions/documentation always sorted (and potentially grouped) by release, eg:

# how to do X

## Qubes OS 4.2
sometext relevant to 4.2 release

## Qubes OS 4.0, 4.1
sometext relevant to 4.0 and 4.1 releases

## Qubes OS 3.0, 3.1
some instructions relevant to 3.0 and 3.1 releases.
The structure could be a bit different than above if the instructions are almost the same
Eg.:
- common instructions
- for 3.0, do x ; for 3.1, do y
- common instructions
- ...

Fast forward in the future, let's say we're now at Qubes OS 5.0. Someone reading the doc above will understand that the instructions haven't been verified to work with the new release.

Note - in the example above, 4.1 could have been appended by a contributor who tested that the instructions shown to work with 4.0 actually worked for 4.1.

Compare that to the two examples below:

# how to do X

sometext

or

# how to do X

## Instructions applicable to all versions of Qubes OS
sometext....

## Instructions specific to Qubes OS 4.0
sometext...

## Instructions specific to Qubes OS 3.2
sometext...

In both cases it is impossible for someone to understand if the instructions are applicable to 5.0:

• someone might have verified that they work and found there was no need to update the doc
• or nobody has ever needed to use that doc for 5.0 (or someone did but hasn't bothered opening an issue/PR to say instructions weren't applicable/working).

[awokd]

Content moved to https://forum.qubes-os.org/c/guides/14.