Thoughts about moving to a different Documentation platform?

75 views
Skip to first unread message

Nicklaus McClendon

unread,
Jun 12, 2016, 3:30:32 PM6/12/16
to qubes-devel
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
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
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.

Marek Marczykowski-Górecki

unread,
Jun 12, 2016, 3:58:44 PM6/12/16
to Nicklaus McClendon, qubes-devel
-----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-----

Andrew David Wong

unread,
Jun 12, 2016, 4:49:48 PM6/12/16
to Nicklaus McClendon, qubes-devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Thanks for your feedback! There's been a lot of discussion about this
both on the mailing lists and GitHub (which you can search for, if
interested) and internally over the years.

One of the main reasons we decided to migrate from the TracWiki system
to the current system is your Con 2. Since Qubes is a
security-oriented operating system, it's significantly more important
than in the case of other OSes that we safeguard the legitimacy of the
documentation and that users have a way of verifying the integrity and
authenticity of all content and changes. People who need a secure
operating system may be more likely to be the targets of attacks, and
the documentation can be used as an attack vector (MITM,
misinformation, etc.).

The principal shortcomings you identify in the current system are not,
IMHO, inherent limitations of the GitHub/Jekyll platform. Rather, I
think they're symptoms of the fact that the documentation is
maintained almost entirely by a motley collection of volunteer
efforts. In other words, there is no one person whose job it is to
make sure that all the documentation is kept up-to-date;
well-organized; edited for content, style, and diction; consistently
formatted; etc. To do it right is a major undertaking, larger than
many realize (like writing a book, then continuously revising it --
forever).

[Personal note: My part-time role as community manager includes only a
subset of these documentation tasks, and even then only as a low
priority when things are slow. I still do as much as I can on top of
that in my dwindling free time, but, unfortunately, I also have to
work for a living outside of Qubes. I'd love to work on all of this
full time someday and raise the scope and quality of our documentation
to the level of other major OSes, but right now the project needs to
prioritize its limited budget on development. (As a user of Qubes who
depends on it daily for security, I fully support this!)]

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJXXcrcAAoJENtN07w5UDAwMM4P/1agI5eCY1EGDK63rfoq2q/Z
uyx1lP0O3dbRztLeTyKcq7hLEiaU9KTj65kp8CsUBq/wfVKcgwBHXekCFxbvdrz4
0NnVTAZMb+UpvKwzRt8RnltSPN0MUWV0ovjPf2JAX/fwvJk6ZkvRym5Fug7oYbP4
G85FknnsgMDlrXPKV/hM2RoQy1iCGF2u4c2o1K0dwcYJZHhoSHr/EsUL5+mLhdxL
5vYEfOmykwa/KW5uTamr20otapN/RgW+iQsMvHo8DiO23IcSEXYfO9GsBDhX87BF
JhXC7c/T7sWeApyNR2f1byjVVFuiGjN/ldx8eH4qgvQt2sU16TsS2WDFoIllinXy
Ef9JAtiAEYWpmG5O0E6y+by6pEk4elJXBOuxvgblWmKLX9TKozmAlVbdySVRS4/U
DYeH64fetP5OS5kIFaPlGlo9ONugRGs4aY0+ev2QCVLpix8gd2fgVhXVd/j8GQU/
eR6r4x/UG3qGYpBwlxJOfClSWrYIgwmH0uYbBxHkStWYMktpu7V+S7f5UwBFlqri
zSs4nG49QmcZYeO2Ovl07JsxMlo9fx9pXhif7mEcvstJfRbJX3/9GEy2mK6cIao4
QzGlMJm6plYVR9ip3qyoJ7FOxXkvq3q6w59iRYKPSrpTU2hbf5XDV2TWCblMs730
18pIoSHhmtCWD4CTla71
=WXrm
-----END PGP SIGNATURE-----

Jeremias E.

unread,
Jun 14, 2016, 11:40:24 AM6/14/16
to qubes-devel, nicklaus...@gmail.com
Hello,

actually Gollum is a wiki system written in Ruby and it saves articles in a Git-Repository.

https://github.com/gollum/gollum

authentication could be provided via GitHub and this plugin

https://github.com/arr2036/omnigollum

there would be some work required to integrate the complete qubes-doc, but maybe it pays
of since editing pages is much easier compared to using GitHub or git itself.

Compared to GH pages, gollum requires a server to run.

Best regards
  J. Eppler

Jeremias E.

unread,
Jun 14, 2016, 4:32:27 PM6/14/16
to qubes-devel, nicklaus...@gmail.com
Hello,

I cloned the qubes-doc repo and started gollum. I did not modify the qubes-doc repo at all (expect the Home.md).
See the attached screenshots of my little experiment.

Best regards
  J. Eppler


gollum-all-files.png
gollum-edit-mode.png
gollum-history.png
gollum-history-compare.png
gollum-search.png
gollum-vs-qubes-doc.png

Andrew David Wong

unread,
Jun 14, 2016, 10:38:22 PM6/14/16
to Jeremias E., qubes-devel, nicklaus...@gmail.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Thanks for investigating this. I see a few cons. I may be wrong about
these because I'm not familiar with Gollum. If so, please correct me.

1. The authentication mechanism would have to be something less
secure, less open, and more centralized than PGP-signed git
commits/tags.

2. We would have to pay for a server to host this. We can't afford
that. By contrast, GitHub Pages + Cloudflare is free. Someone will
probably also have to take time away from other work to administer the
server when things inevitably go wrong.

3. The functionality looks largely the same as what GitHub already
provides. (If users want special functionality that only Gollum
provides, or want it locally, they can install it locally as you just
did.)

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJXYL+UAAoJENtN07w5UDAw9ysQAI5JxqVv49VfUY51776WurvN
agxtz+JeWBiPmrtPBZxdqnTHM38chCCWzuqrmOvgAO95l1vJq6HQpwgwKDATeaNt
a6mnnYrzslezv0A2UqPjQKwHimsAw3zcF2Xwjl7lwe3KDh/5KR3Gu9yT2nylcq52
uO7xYRhRjgna3MG9YuEbgMtbOGW0+a5Ij5W/ZZb8iPoWfD2y3qykl0Q40y0BlgzN
ZLV9sXbiG3vjRVw6Pm5+5Hn+6f5CS2+Qkoy3dTTuexd8EpqjFmd9uYM0J0XWPT3B
fSn0xesdQ2PxEDInSycBNCIwFehHYTiavbDHWskRFzpOIdLCpWv1RtSInadwM14g
fgScdj0QenaqPJZ3ZuB8vHwJ/BzmheexMt7kvBnhpXwwJYf0nqqH5RvEmkACXKDR
qe3UqHTdzocI24UuidlzADDB654Ihsn0HQZJFSH3SjK4sITpAjRjevO7uMMIUrOQ
W/LMOmHDK5NSU+FZahrVy2Dy3Nm+y9FEiHbxcxT06F1dC7dvJvNtKpDFIYRTzblX
EJCrkU7InWDy2+qtSxsPAZGPJ+ZuI+XJWMo7UEKQdFjttIqbgYJehNya3o/hwxQD
z6UOQCD1RCKMx+OrWx1zFO3s6hFVEVqcr3R/Y4miCYUZrn9zVrfovqAUN+GbQn7F
+mSc3S01GB2G86YMqhbI
=OeKj
-----END PGP SIGNATURE-----

Jeremias E.

unread,
Jun 15, 2016, 11:44:01 AM6/15/16
to qubes-devel, j.ep...@openmailbox.org, nicklaus...@gmail.com
Hello,


1. The authentication mechanism would have to be something less
secure, less open, and more centralized than PGP-signed git
commits/tags.

I am not sure what you mean by that. As far as I understand the current solution requires GitHub to be able to contribute to the qubes-doc repo.

PGP-signed git commit/tags would be still available in Gollum, since Gollum uses Git as storage system for wikipages. Gollum pulls the history from
the git repository (see above gollum-history.png of the archlinux article).

Every time you edit and save a page Gollum does all the git commit etc. commands for you. That is the big advantage of Gollum.

Gollum itself does not provide any kind of authentication. Authentication could be provided through third parties like Github.
 

2. We would have to pay for a server to host this. We can't afford
that. By contrast, GitHub Pages + Cloudflare is free. Someone will
probably also have to take time away from other work to administer the
server when things inevitably go wrong.

Gollum can also produce static sites.

Do you use GH-Pages or Cloudflare?


3. The functionality looks largely the same as what GitHub already
provides. (If users want special functionality that only Gollum
provides, or want it locally, they can install it locally as you just
did.)
 

Maybe.

I intention was more to show that there is a solution for some of the problems the
initiator of this thread was recognizing.

In addition my small experiment went surprisingly well,
so I wanted to share it with you.

Best regards
  J. Eppler


Andrew David Wong

unread,
Jun 16, 2016, 11:38:49 AM6/16/16
to Jeremias E., qubes-devel, nicklaus...@gmail.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2016-06-15 08:44, Jeremias E. wrote:
> Hello,
>
>
>> 1. The authentication mechanism would have to be something less
>> secure, less open, and more centralized than PGP-signed git
>> commits/tags.
>>
>
> I am not sure what you mean by that.

I was referring to what you said here:

>>> authentication could be provided via GitHub and this plugin
>>>
>>> https://github.com/arr2036/omnigollum

The description of that plugin sounds like it requires/relies on
centralized services.

> As far as I understand the current solution requires GitHub to be
> able to contribute to the qubes-doc repo.
>

No, a GitHub account is not currently required. It does make things
easier, however, and it is free (as in beer), so in practice almost
everyone who wants to contribute uses it, but we do not strictly
require it. (For example, it is possible to send Git patches via email
instead.)

> PGP-signed git commit/tags would be still available in Gollum,
> since Gollum uses Git as storage system for wikipages.

Ok, that's good, then!

> Gollum pulls the history from the git repository (see above
> gollum-history.png of the archlinux article).
>
> Every time you edit and save a page Gollum does all the git commit
> etc. commands for you. That is the big advantage of Gollum.
>

Not sure if this is really an advantage, especially for people who
already know how to use Git. Will we have meaningful commit messages,
for example?

> Gollum itself does not provide any kind of authentication.
> Authentication could be provided through third parties like
> Github.
>

See above.

>> 2. We would have to pay for a server to host this. We can't
>> afford that. By contrast, GitHub Pages + Cloudflare is free.
>> Someone will probably also have to take time away from other
>> work to administer the server when things inevitably go wrong.
>>
>
> Gollum can also produce static sites.
>

Ok, but is the automation comparable to our current setup?

> Do you use GH-Pages or Cloudflare?
>

We currently use both.

>> 3. The functionality looks largely the same as what GitHub
>> already provides. (If users want special functionality that only
>> Gollum provides, or want it locally, they can install it locally
>> as you just did.)
>>
>
> Maybe.
>
> I intention was more to show that there is a solution for some of
> the problems the initiator of this thread was recognizing.
>
> In addition my small experiment went surprisingly well, so I
> wanted to share it with you.
>

Yes, and I appreciate that! I replied because I found your suggestion
to be worth seriously considering and deserving of a frank response. :)

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJXYsf6AAoJENtN07w5UDAwessQAIV52Zw95yYJyxloXltEkUjW
rdULs7CBgIRdRB0Plt5dHNu9d4xlNPEhY6sEQZBwx4LuLMhLg3VZZ7XfGD//IIac
alQozkmNT6fkZ00TUo1wmdCeMYhau00SewmTgLdxJsjBjXUjUmRcVHG+8ZPeRjCv
67MUp3whSMXxDVdugzIABvexLcU5FVRVG/bWtig069e2/fZlT2fQMGOKSH82PqqY
GUKwYbfnyS0Inpi+3hVE2PhFJxI/yIIaS/o/iz7OT0BCJDnhbw7CNLUVaTr8od7b
FP5TlpmTLDrnn5oZ7FsDfQTDJRkTx21CWAmrpice9mNc99QxThOI+tKswzaGbwhw
VP8yljzwzkf1SnbQD9cBBJ73cJGry8n95sw1OYM4zl9pa9QpTXkDD9+3CQkcI/jR
N6vb1JeeLpKTX2zedE7lZPKj+qK23vXjOG32UXlSpWPXfbyxGkK7ws4xqL6r/fiU
9J7fDsKngxIJQBUywJrPiaDxY9NS5G9RD8CBXPnQYHJJvpX20p9rTIUdITcZxB5y
fUoDMXLOFPcx44v8RNKHgPvoKDLbFu9oz81Qnu4/v+b0wII/LiE0oAJVrL6l7YGf
Ql2MoctZ3c75d+P4HHZozLm9fNlmQ2UgDTsRzBn8Z3kwqeNKIiYlzQZjFhws1R0L
X1v6vBp1IIHuLMg8olsN
=LkH6
-----END PGP SIGNATURE-----

Reply all
Reply to author
Forward
0 new messages