-----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 > <kchr+qubes-de...@fripost.org> 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 QmV2cDJanU9AEfTJjifWQF3hB3vpxIRMdxxNI2KK/pHQlM43ni7UealycaM3TO4J 3wrCL7RTpvfhcopXnsuUymERkhkrq56f7mvHTf4i/H3ntsWngiJGzmgA0FoXKFbF 0QLf67y4A5mdGtJOuy+HIBTIik8Stijlk0KL4oCv+PmHU6Rzwwj8BZ8Vj5/pQWH5 iboDQRjwrbvcmpd4nBBK55CcGUMCbcnXWFCWTSILhz/DIciV2M+fJoq1WQiE35nO o1NR2wYexwL7HG1PMcOibs3it7O1N55rqpaNGhdG6bhfUF+2k8pL3Kx+I52MWO1Q bd6Th888G59kdD/7RjdUrn4UlAR3LUKsOJU6JCW5xxxpBz/qD1WbkQnLVIzpf0gS o/ItskRiNhCxC9hSePu86WcAA8lwRXd7foXQrCKTBvx2eaBtSqN2Gdjiq3hcmwzp PC3p1F44105L8uEzos9mIyqwiclilUsbS+UpAyD/tWEzKAWA35zm891c5UIMnCJl IHNJ9ZURKlFuN7QViixf =Aja8 -----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/20170708230530.GL2697%40invisiblethingslab.com. For more options, visit https://groups.google.com/d/optout.
