Re: [qubes-devel] Re: Managing the Qubes Documentation

2017-07-08 Thread Wojtek Porczyk 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On Sun, Jul 09, 2017 at 01:05:30AM +0200, Wojtek Porczyk wrote:
> Well, for source documentation we use Read The Docs
> (https://qubes-os.readthedocs.io/projects/core-admin/en/latest/)

Oh, and I forgot, that is also available as
https://dev.qubes-os.org/projects/core-admin/en/latest/.

Sorry for confusion, the second one is canonical.

- -- 
pozdrawiam / best regards   _.-._
Wojtek Porczyk   .-^'   '^-.
Invisible Things Lab |'-.-^-.-'|
 |  |   |  |
 I do not fear computers,|  '-.-'  |
 I fear lack of them.'-._ :  ,-'
-- Isaac Asimov `^-^-_>
-BEGIN PGP SIGNATURE-
Version: GnuPG v2

iQIcBAEBCAAGBQJZYWWlAAoJEL9r2TIQOiNR2/kP/0RoD5G5cdtFoZtG+qSLvKHJ
+Hp9mNiFUdy9vf7cnOXjGTXULUf/JkAUHtvjUsXvua7Wx5jQVSyP/0eEEe/P8U09
RjeLAJc29hkADrZLIuS2XTt9+oTLWUj7r7BFlSMFdNqSSQ7NNOWW3r4V4/e4axBG
X9M9oFgnFahsYcqsMvivVxNlyEdU76j4k0btYrmSSQkXGdzx891TwmfjYs2xAKLN
asl6ve20t6i/QFLKvrSRHI+g2AJ+BWtaGxdudRawjjes7SuaIkWPDPD85/lkcide
dOK6fY7rnybB8QSOaNG7iYLQh+eSY70/Mk4VLyciYcsrIxEIN1qD5wVqB0QfOtLu
FUPYtoSdsDwJ9J17StKRF23qg44ga1hMYFB/BbDar6N/FBSZR7qOUQN6XMk14Uef
6t1a7q599/miBq1ue00Q2qWpa3DUlTgPk5K6AHpp+ib6DeeupsiuqhjZX3iRmFN0
NP70kBGmYCqcUl5VQKHIaL0wUWYb6fW5Ly4pnuxTwxi8xW/wBoAeE/6fzZHDZelN
qex4WmgD5E3l1nykSrsLLCPPnWczorB+i7DAjelOuiXsm+4AHby6gbR9l6hrh+Sm
wfUZr6aBzi2eHtcOqTh6blpz68EyZVjAXbmSmkh/Wj3uhQrBZzpT2lC/DIR8IBNl
ygbhdGYnQK6UKgJKoO7O
=YOxM
-END PGP SIGNATURE-

-- 
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 qubes-devel+unsubscr...@googlegroups.com.
To post to this group, send email to qubes-devel@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/qubes-devel/20170708230717.GM2697%40invisiblethingslab.com.
For more options, visit https://groups.google.com/d/optout.

Re: [qubes-devel] Re: Managing the Qubes Documentation

2017-07-08 Thread Wojtek Porczyk 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On Sat, Jul 08, 2017 at 03:23:22PM -0400, Jean-Philippe Ouellet wrote:
> On Sat, Jul 8, 2017 at 2:45 PM, Noor Christensen
>  wrote:
> > On Thu, Jul 06, 2017 at 07:40:21AM -0700, Andrew Morgan wrote:
> >> On 07/04/2017 03:25 PM, je wrote:
> >> > Hello,
> >> >
> >> > we should have a mechanism to manage the state of the documentation. The
> >> > documentation is only helpful if the documents reflect the actual
> >> > situation of Qubes OS. For example, documents which are written for
> >> > Qubes v1 or 2 are outdated. Wikipedia displays certain meta information
> >> > above articles which are outdated and/or need to be reviewed to reflect
> >> > the latest changes. My idea is to have a similar mechanism. For example,
> >> > it would be helpful to look after every Qubes OS, Fedora or Debian
> >> > release through the documentation and mark the documents which need to
> >> > be updated for the new release. In addition, it would be helpful to
> >> > create an issue for every outdated document. This way it would be easy
> >> > for the community to contribute to the documentation.
> >> >
> >> Additionally documentation version snapshots would be great. Being able
> >> to choose a version of the docs from a dropdown list for each QubesOS
> >> version would help keep things less cluttered as we start to have a
> >> split in users using v3 and v4.
> >
> > I think this is a better alternative than keeping a single document up
> > to date with the latest changes.
> >
> > Since we are using plaintext as backend for the docs, we could use git
> > branches or tags to juggle the versions. When we generate the output
> > HTML files the branch or tag name could be used as path prefix or
> > suffix, like this:
> >
> > [branch qubes-doc/3.2]  https://www.qubes-os.org/doc/3.2/usb/
> > [branch qubes-doc/4.0]  https://www.qubes-os.org/doc/4.0/usb/
> >
> > The build script could also add this version information as some widget
> > in the output HTML, like dropdown at the top of each page that
> > automatically selects the current version. We don't even need Javascript
> > for that... ;-)
> >
> > -- noor
> 
> I see two main problems with such an approach:
> 
> 1) The site is actually generated by github-pages's infrastructure,
> which is a somewhat restricted process. In theory, the multiple branch
> setup you propose sounds nice, and if the site was generated via our
> own scripts this would indeed be easy. However, I am not aware of any
> way to do this using only base jekyll with only the plugins available
> via github.

Well, for source documentation we use Read The Docs
(https://qubes-os.readthedocs.io/projects/core-admin/en/latest/) and they
have version support built in. The source lives in either several branches,
one branch with tags, or some combination thereof. Currently we have just one
version built from current master (rtd call that "latest"), but starting with
R4.0 we could keep the documentation for past versions.

We did this separately from qubes-os.org and github for two reasons: one was
to have documentation for the code in the same repo as the code documented,
which makes keeping documentation up to date easier. Second reason was that
we wanted to use Sphinx to generate documentation (at least for Python code,
which is probably the only code actually documented :/). That wouldn't play
with github as nice as RTD makes it.

Now those reasons are why we probably don't want to have higher-level
documentation together with that. For one, we have many different repos and
for some high-level guide that uses several components there would be
ambiguity where to put it. Also, many articles are applicable to several
releases and it would be hard to maintain them in several branches in
parallel.

So I don't think there should be many outdated articles outside of those that
are obviously version-specific (like those around releases).

> 2) At the end of the day, this just creates more work. From my
> perspective it seems less maintenance overhead to simply maintain
> inline comments noting things may only apply to a particular Qubes
> version, than it would be to try to maintain two separate but intended
> to be mostly-parallel version of the same docs. This is especially
> true since many updates to the docs are not specific to a particular
> Qubes version, and would need to be manually applied to both branches.


- -- 
pozdrawiam / best regards   _.-._
Wojtek Porczyk   .-^'   '^-.
Invisible Things Lab |'-.-^-.-'|
 |  |   |  |
 I do not fear computers,|  '-.-'  |
 I fear lack of them.'-._ :  ,-'
-- Isaac Asimov `^-^-_>
-BEGIN PGP SIGNATURE-
Version: GnuPG v2

iQIcBAEBCAAGBQJZYWU2AAoJEL9r2TIQOiNRwnMP/iLIe4CefiMlUk9QDfL0HzX9
FCKVhfVg+LOKYwWQyfvtWZDGUFP8QXvdmjwsTQu1PrLY1o7JhgGqFmAwRZtvZnwi
9Whb5JcPvoH3Y1yMPwjLYVA9QoLjBGVh2nPM8S3vpAdv6AFcSj612OErAmOE9YZD

Re: [qubes-devel] Re: Managing the Qubes Documentation

2017-07-08 Thread Jean-Philippe Ouellet 
On Sat, Jul 8, 2017 at 2:45 PM, Noor Christensen
 wrote:
> On Thu, Jul 06, 2017 at 07:40:21AM -0700, Andrew Morgan wrote:
>> On 07/04/2017 03:25 PM, je wrote:
>> > Hello,
>> >
>> > we should have a mechanism to manage the state of the documentation. The
>> > documentation is only helpful if the documents reflect the actual
>> > situation of Qubes OS. For example, documents which are written for
>> > Qubes v1 or 2 are outdated. Wikipedia displays certain meta information
>> > above articles which are outdated and/or need to be reviewed to reflect
>> > the latest changes. My idea is to have a similar mechanism. For example,
>> > it would be helpful to look after every Qubes OS, Fedora or Debian
>> > release through the documentation and mark the documents which need to
>> > be updated for the new release. In addition, it would be helpful to
>> > create an issue for every outdated document. This way it would be easy
>> > for the community to contribute to the documentation.
>> >
>> Additionally documentation version snapshots would be great. Being able
>> to choose a version of the docs from a dropdown list for each QubesOS
>> version would help keep things less cluttered as we start to have a
>> split in users using v3 and v4.
>
> I think this is a better alternative than keeping a single document up
> to date with the latest changes.
>
> Since we are using plaintext as backend for the docs, we could use git
> branches or tags to juggle the versions. When we generate the output
> HTML files the branch or tag name could be used as path prefix or
> suffix, like this:
>
> [branch qubes-doc/3.2]  https://www.qubes-os.org/doc/3.2/usb/
> [branch qubes-doc/4.0]  https://www.qubes-os.org/doc/4.0/usb/
>
> The build script could also add this version information as some widget
> in the output HTML, like dropdown at the top of each page that
> automatically selects the current version. We don't even need Javascript
> for that... ;-)
>
> -- noor

I see two main problems with such an approach:

1) The site is actually generated by github-pages's infrastructure,
which is a somewhat restricted process. In theory, the multiple branch
setup you propose sounds nice, and if the site was generated via our
own scripts this would indeed be easy. However, I am not aware of any
way to do this using only base jekyll with only the plugins available
via github.

2) At the end of the day, this just creates more work. From my
perspective it seems less maintenance overhead to simply maintain
inline comments noting things may only apply to a particular Qubes
version, than it would be to try to maintain two separate but intended
to be mostly-parallel version of the same docs. This is especially
true since many updates to the docs are not specific to a particular
Qubes version, and would need to be manually applied to both branches.


Regards,
Jean-Philippe

-- 
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 qubes-devel+unsubscr...@googlegroups.com.
To post to this group, send email to qubes-devel@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/qubes-devel/CABQWM_CYJvR%3DDQ-iOOUyLLbCzOFTyJ_dtszfPL0LSbXVny9XZg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[qubes-devel] Re: Managing the Qubes Documentation

2017-07-06 Thread Andrew Morgan 
On 07/04/2017 03:25 PM, je wrote:
> Hello,
>
> we should have a mechanism to manage the state of the documentation. The
> documentation is only helpful if the documents reflect the actual
> situation of Qubes OS. For example, documents which are written for
> Qubes v1 or 2 are outdated. Wikipedia displays certain meta information
> above articles which are outdated and/or need to be reviewed to reflect
> the latest changes. My idea is to have a similar mechanism. For example,
> it would be helpful to look after every Qubes OS, Fedora or Debian
> release through the documentation and mark the documents which need to
> be updated for the new release. In addition, it would be helpful to
> create an issue for every outdated document. This way it would be easy
> for the community to contribute to the documentation.
>
> Best regards
>   J. Eppler
>
> --
> 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
> qubes-devel+unsubscr...@googlegroups.com
> .
> To post to this group, send email to
> qubes-devel@googlegroups.com
> .
> To view this discussion on the web visit
>
https://groups.google.com/d/msgid/qubes-devel/04281dee-4fbe-46ec-b31f-fd76244756f2%40googlegroups.com
>
.
> For more options, visit https://groups.google.com/d/optout.

Additionally documentation version snapshots would be great. Being able
to choose a version of the docs from a dropdown list for each QubesOS
version would help keep things less cluttered as we start to have a
split in users using v3 and v4.

Andrew Morgan

-- 
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 qubes-devel+unsubscr...@googlegroups.com.
To post to this group, send email to qubes-devel@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/qubes-devel/ojli4i%24i92%241%40blaine.gmane.org.
For more options, visit https://groups.google.com/d/optout.


signature.asc
Description: OpenPGP digital signature