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. 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.
