suggestion for quakity assurance of documentation

[kai....@gmail.com]

greetings!

while taking first steps with new qubes 4.0, i find that some of the great documentation articles in qubes-os.org
are no more 100% accurate for qubes 4.0 (see my previous post on usage of kernel 4.16 for an example). this is quite expectable, given that both the api as well as the technical implementation details of qubes changed a bit between 3.2 and 4.0. however, this coukd make it difficult for the average (or below average) user like me to decide wether the information found us accurate for 4.0 and therfor can safely applied to 4.0.

so my suggestion is to add a creation/last updated date to the pages and/or to add an information, to which versions of qubes the article applies, e.g. created for version 3.2, updated/reviewed for usage with 4.0.

any other/better solution would be also welcome, of course...

thank you and all the best
Kai
http://kai.froeb.net

[Ivan Mitev]

hey,

On 04/04/2018 11:46 AM, kai....@gmail.com wrote:
> greetings!
>
> while taking first steps with new qubes 4.0, i find that some of the great documentation articles in qubes-os.org
> are no more 100% accurate for qubes 4.0 (see my previous post on usage of kernel 4.16 for an example). this is quite expectable, given that both the api as well as the technical implementation details of qubes changed a bit between 3.2 and 4.0. however, this coukd make it difficult for the average (or below average) user like me to decide wether the information found us accurate for 4.0 and therfor can safely applied to 4.0.
>
> so my suggestion is to add a creation/last updated date to the pages and/or to add an information, to which versions of qubes the article applies, e.g. created for version 3.2, updated/reviewed for usage with 4.0.

the problem is that things like a trivial typo fix would automatically
update the 'last updated' tag and make people think that the doc is up
to date for the last qubes release.

alternatively, the 'last updated' tag could be updated manually when
there are significant changes, but it's error-prone.

the consensus seems to be to fix the current documentation with "R3.2",
"R4.0" tags where appropriate. One of the problems is that the core devs
had too much on their plate with the recent 4.0 release so the
documentation is a bit lagging.

here are some related issues:

https://github.com/QubesOS/qubes-issues/issues/3495
https://github.com/QubesOS/qubes-issues/issues/3629


btw if you don't have time to contribute/fix the documentation, listing
the problems you saw in the docs would be helpful (either post them here
or send me an email).


ivan

[sevas]

where is your email? I will email you.

I too have found many problems.

[trueriver]

On Friday, 6 April 2018 09:46:00 UTC+1, Ivan Mitev wrote:
> ...

> the problem is that things like a trivial typo fix would automatically
> update the 'last updated' tag and make people think that the doc is up
> to date for the last qubes release.
>
> alternatively, the 'last updated' tag could be updated manually when
> there are significant changes, but it's error-prone.

The solution used on a number of wikis is to supply a checkbox "This is a trivial update" and a text box to describe the purpose of the update. Edits will not be accepted where both the checkbox and the purpose are blank. This eliminates most of those kind of errors. (Nothing is perfect of course)

That would be my preferred solution, FWIW

[trueriver]

btw:

I assume the apparent typo in the topic title is deliberate ;)