-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
On 2017-01-22 06:23, loeken internetzme wrote:
> I have added another part to the playlist ( Qubes/Windows 7
> dualboot).
>
> The way to multiboot described in the documentation always gave me
> an error message that my windows boot was damaged (but when
> booting off the windows disk directly, it booted without problems).
> That was one of the most asked questions on the video tutorials so
> far, "how to get dual boot working", maybe somebody should take a
> look at the documenation, if that part is outdated or something,
> all i basically did was use a slightly different
> /etc/grub.d/40_custom
>
> A few suggestion on the side: I personally like the docs, I did
> notice that some parts seem to be outdated and havent been
> tested/updated with a recent version. I dont know about the cms
> you use but might it be possible to add 2 types of information to
> each documenation post?
All the docs are Markdown files hosted from the qubes-doc GitHub repo,
and the site is built with Jekyll. You can read about this here:
https://www.qubes-os.org/doc/doc-guidelines/
The documentation is almost entirely a volunteer effort. You're more
than welcome to contribute!
> 1.) The date/author who wrote this ( so we the user have an
> understanding of how "up to date" this documenation is,
There's an open issue for the timestamp part:
https://github.com/QubesOS/qubes-issues/issues/2169
Haven't figured out a good way to implement this. Help wanted.
However, this actually isn't much of a problem, because you can
already easily click through to the source page on GitHub (a
convenient "View Page Source" link is provided on every doc page) to
see the last commit date and who authored the commit. You can even see
who contributed each part of the doc.
> or who to contact in case we find some problems worth updating,
> maybe even add a mailto:
upda...@qubes-XX.org href there, or
> whatever you use )
If you find a problem, please edit the page! There's a convenient
"Edit This Page" link on every doc page that takes you directly to an
editor in GitHub. You can then submit a pull request to have your edit
merged.
I appreciate the suggestion regarding an email address, but frankly, I
think that trying to do accept doc updates via email would be
*extremely* sub-optimal relative to our current pull request model,
since it means that someone would have to monitor this email address,
people would try to submit doc updates in all manner of possible
formats, and the maintainer would have to somehow convert these
formats into a format compatible with our system. It would make the
process much more labor intensive while simultaneously encouraging
low-quality submissions, which would be very inefficient and
unproductive overall, IMHO.
(I've added a link to the Documentation Guidelines page to the
sidebar. I hope that this will make it easier for users to find out
how they can contribute to the docs.)
> 2.) Which version of qubes this has been tested with
>
> Most users that are familiar with qubes probably know roughly when
> which parts got added etc, but for the new user i think it might
> be a good indication to know how "fresh" this documentation is.
> For example there is a documenation which talks about how to build
> prop nvidia drivers and it contains kernel versions 2.6*, so it is
> clearly outdated, and it did not work for me at all.
>
Generally, the docs are supposed to apply to whichever Qubes versions
are currently supported, but I agree that it's better, in many cases,
to explicitly state which version of Qubes a certain set of
instructions has been tested with. (We already do this on many
important doc pages, such as the pages on updating Fedora templates
and emergency backup recovery.)
I've added a point in the doc guidelines encouraging contributors to
do this:
https://www.qubes-os.org/doc/doc-guidelines/#contribution-suggestions
>
> Another suggestion would be to allow users to comment the
> documenation ( such as "warning I tested the installation of
> nvidia drivers, but i failed, the documenation is outdated" ). That
> would probably satisfy users a lot by not spending a lot off time
> on the same problems, coming to the same conclusions.
It's already possible to do this, and users are encouraged to do so!
As mentioned above, anyone can edit the docs and submit a pull
request. This includes adding a note with a link to a discussion
thread, indicating that the user had trouble on a certain version of
Qubes.
However, let me warn you about something that I have seen commonly
happen: A user will *incorrectly* try to implement a set of
instructions, conclude that the instructions (rather than the user
himself or herself is at fault), and submit a bug report or doc edit
stating that Qubes and/or the docs are broken. Obviously, we would
like to avoid these kinds of spurious reports and updates, since they
waste valuable time, so there is an advantage to not having *too* low
of a bar for people submit claims of this kind.
Having said that, I've also added a point in the doc guidelines
encouraging contributors to add such comments after thorough testing:
https://www.qubes-os.org/doc/doc-guidelines/#contribution-suggestions
> I understand that you prefere google groups for your workflow.
(Google Groups is just for the mailing lists.)
> Maybe just link in a google group post like this to every
> documenation, that would allow users to give their input and you
> guys(and girls) to keep using your workflow with google groups
>
Users are free to make threads in the mailing lists about
documentation issues (and many do). I think it makes more sense to
create threads and link them in the docs only when there is something
to talk about, though.
> And my last suggestions since im already bashing the doc hard (
> altough i do like it ;) ). The troubleshooting sidebar on the
> right. It would be better to disable that on mobile devices, it
> takes up half the screen on my mobile.
>
The website uses a pretty standard responsive design scheme that
automatically moves the side bar to the bottom at narrow screen
resolutions. It sounds like maybe you have an "in-between" resolution
that doesn't trigger this. What resolution is your mobile device's
screen? Maybe we need to tweak the thresholds.
iQIcBAEBCgAGBQJYhflAAAoJENtN07w5UDAwBr0QAMlUQdqWUhNCeqAwgBwVB6gv
HN2WF2EnGzLYXdUb2pAXfsY8pu1lucdy9VZ3g42OzeNCEwa5MnVjF8ad+hZ1hKzc
NqyIYJhKbIwQdmOcpJkNUXyLyPdp+aH3X0EZI0LJVMsJn09LYV+qXU6CryY2ffzi
tbu4goMtUU1wf4KLPVSohjeoOlQqw1wxEmUQSTsjTMlW9MxoDtUCJztubnnD9T6Z
VU0kSqvxqc3ZUXXgqM3Extn4a8e0RIOwhLeX/3ZChjEW5mlRldrOLjIGP3jQEurU
RwxhScVBiOsduAbPdzACDM072oIjpyq/7fz+y3t/y2Hy78hNQQg8xDsASaCwwb7g
vy/ABWCLnUL3A35Bu+rJ0z5VWSr9Vy2QgkLQzjOnz+ePxTQpsSQRFBghpM8h8YNr
D2dQjN2+J5Gmr4xd9ptef3XuwXDIPvuZtNVos6KZgDK/zeyEXQJRZ0mvGqFVvwM9
U2i5lFMed0/LUvNFHDzaWjMljW5e3kpJi0EgHW7BN2mSAawoZHz7Le3iqWgG9m/B
UmPt3RQqYVwtsev1FuCoKQDHIUPHRUkxuLreKzk6gnT4HxFna+m81kVqRVJMXQU7
lciv1Jz4YAt48jBGx1UG3JLPUGkzyDE4d6BlqWhaCzoKJxqx0GCoI5qcjFxG4W1h
NRz5dNf8in3Ov5mPg2Ys
=PqGQ
-----END PGP SIGNATURE-----