-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On Sun, Jun 12, 2016 at 12:30:32PM -0700, Nicklaus McClendon wrote: > I personally think using Jekyll pages for documentation may not be > sustainable in the long run. Although I know the new core-admin > documentation is utilizing readthedocs, but I think a Wiki might be a great > option for user documentation for the following reasons: > Pros: > 1) More familiar and user-friendly interface. The current table of contents > style Jekyll page is becoming more and more cluttered and difficult to > categorize. Compared to something like the Arch Wiki (perhaps an overused > comparison, but a good one in my opinion), the Qubes documentation leaves a > lot to be desired. > 2) The ability to add application specific information without adding > clutter. Users could document program specific elements that are beneficial > to know using Qubes, like how to properly sync Urxvt themes or Firefox > extensions from a template VM. With a wiki, it just becomes another page > that can be searched for and doesn't need a direct link. In the current > setup, each page should be linked to from the index page, which will (and > currently is in my opinion) become unwieldy
The above two have very little to do with chosen platform, it's just a choice of documentation layout. We have chosen to have a single (potentially long) index, so every page is accessible with at most two clicks. Somehow inspired on help.github.com. > 3) Easier user interface. Currently, only those familiar with git and > github can update documentation. While this is not necessarily a bad thing, > I do not believe the groups of people who cannot use git and those who can > write good and useful documentation are mutually exclusive. Edits can still > require approval before they go live, similar to how Andrew currently > moderates pull requests on the qubes-doc repo It is possible to edit pages without direct git usage, within github web interface. Take a look here: https://www.qubes-os.org/doc/doc-guidelines/#tocAnchor-1-1-2 It requires few more steps than just "edit" + "save", but not much more. Maybe this documentation should be linked somehow near "Edit this page" button? > Cons: > 1) Harder to have easily accessible offline documentation. I feel, however, > this is less important for Qubes than an OS like Tails. > 2) Signing updates. All git commits are signed, meaning I can download the > documentation and be certain that Andrew (or another member of the Qubes > team) signed off on a documentation change/update. I am not sure if this > can be done on a platform like MediaWiki. We had git-based mirror of trac wiki in the past. It wasn't signed (because changes done in web interface wasn't signed in the first place). The major problem with such approach is ability to restore/mirror. If git isn't supported natively, setting up mirror always will require some additional step (even if that would be just "load data from file"). In case of jekyll, it's just a matter of "jekyll serve". And it updates automatically when you pull new changes. - -- Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing? -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQEcBAEBCAAGBQJXXb7sAAoJENuP0xzK19csGR0H/iiHCq7k1HxtrfLDmnio5oze 9AR737j+AYWJDbtcBV76f1r8HI5WeKGVSd0lQwgbAI4HMwzCo+iN5gC3uO8rFT9N FTOJZP8rDxFRNOuFeI7NpeST5tmW26YttJkRUiZO9YE/ysOuZQ7XKml3xxaFPK7/ QzRT1zNtAhWgye8jGClnv5DjQx3fPJ/CY95AbZWlILzq9XfWuRnn2isEPr/9xG7f AM3105i+rj2g6fHyiJaWF/fBN01RphDUJcC+UVUh16HHmFYsub3h3ARKnIJguslQ +iQpAlpaOmZ1qRpRGtc6SHCUx+49xhvzn96dFiJOG2R6QpqXVpQJtU05re8oK04= =tktc -----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 [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/20160612195836.GK1593%40mail-itl. For more options, visit https://groups.google.com/d/optout.
