[haiku] RFC: Moving the mini guides off drupal

  • From: Richie Nyhus-Smith <richienyhus@xxxxxxxxx>
  • To: haiku@xxxxxxxxxxxxx, haiku-web@xxxxxxxxxxxxx

Hi all,

The guides that are hosted on Drupal [1] are a mess and are quite outdated,
but at the same time editing them with Drupal 6 is not a pleasant
experience.

Although GCI students might be able to assist on this matter, the fact that
students don't have editing abilities on Drupal complicates this process to
the point that it's just far too annoying. [2]

I think it would be worth while moving these guides to a static website
generated by, for instance, the Sphinx documentation generator (which uses
reStructuredText) [3]. The source could be hosted on a github repo [4],
which would allow people to submit changes via pull requests and this
should dramatically increase amount of people contributing to the mini
guides.

The Sphinx documentation generator actually contains a bundled theme that
is a clone of our User Guide [5], so we don't have to do any work getting
it to match our look and style. We actually already use it for
HaikuPorter's development documentation [6].

As these mini guides are meant to use the "wiki-like" template, there
shouldn't be any comment section to worry about,  so it is only a matter of
setting the it up and providing redirects to the new location.

Although I obviously lack the permission to set it up, I am willing to do
the work regarding converting the documents from Drupal's flavour of
limited HTML over to reStructuredText (or whatever if someone can think of
something better than Sphinx).

Thoughts?

Regards,
Richard.

---

[1] https://www.haiku-os.org/guides
[2] The student submits their work in plain text, with the mentor
subsequently adding in the missing formating via HTML or the student
stubmits their work in HTML which the mentor then has to edit the code down
to match Drupal's particular flavour of html.
[3] http://www.sphinx-doc.org
[4] i.e. https://github.com/haiku/guides
[5] http://docs.valence.desire2learn.com
[6] https://github.com/haikuports/haikuporter/tree/master/doc

Other related posts:

  • » [haiku] RFC: Moving the mini guides off drupal - Richie Nyhus-Smith