CAcert System Admins discussion list

[Jan Dittberner <jandd AT cacert.org>]

Dear CAcert system admins, dear community,

the current documentation for our infrastructure systems is spread all over
the Wiki which has some advantages (like low barrier to edit the
documentation) but also some disadvantages (no consistent versioning, lots
of duplicate information, restrictions of the Moin Wiki markup). I thought
about another way to document our systems that is less prone to bitrot and
duplication for a long time and came up with the following:

In the past few weeks I started a proof of concept implementation of
another way to document our systems and would like to get your feedback on
the effort before I copy/update/move the existing documentation and improve
the proposed new system.

I have setup a Sphinx [1] based documentation project that is available in a
git repository [2] on git.cacert.org (Please see [3] if you ask "Why not
github?"). The documentation is stored in a plain text format
(ReStructuredText, abbr. as RST) that is similar to Markdown but provides
better extensibility. The documenation files can be modified with your
favourite text editor (vim and Emacs have great RST support). To ease the
life of all (future) contributors I have setup a job on jenkins.cacert.org
[4] that builds an HTML version of the documentation [5] when changes are
pushed to the git repository. I also documented how to get up and running
with the system in a separate page [6].

*Advantages*

From my point of view the proposed system has some advantages over using the
wiki while allowing co-existence when needed:

* documentation for all infrastructure is versioned together (this is why
  the software development community moved away from file based version
  control like RCS to systems like CVS, Subversion and git today).

* you can use your favourite git frontend (or the cli) to see a changelog
  for the whole documentation (git log), show the differences between
  versions (git diff) and see who changed which part of a piece of
  documentation (git blame ... which can be aliased to git praise if you
  like)

* you can use your favorite editor with proper syntax highlighting to work
  on documentation (I use vim with vim-table-mode [7]) but there are other
  editors that support RST

* currently duplicate or manually synchronized information can be aggregated
  automatically by using explicit text roles. I implemented a small Sphinx
  extension [8] and use that to automatically create a list of IP addresses
  [9] (source [10]) that is cross-linked to the system pages. If those of
  you who actively work on the systems agree to continue we could implement
  similar extensions to generate more lists (certificate list, ssh key list,
  OS list, ...) too.

* Sphinx generates a nicely formatted index [11] and Javascript based full
  text search for the documentation.

* Patches for used software can directly be stored as files and can be
  included as syntax highlighted text blocks inside the documentation. I
  implemented an example for this approach for the OpenERP patches in the
  board system documentation [12].

*Disadvantage*

The only disadvantage that I can see is that drive-by edits are not as
easily possible as with the current Wiki based system. Git provide good ways
to collaborate like pull requests and its format-patch/am email based
workflows though if somebody does not want to jump through the hoops to get
a user account on git.cacert.org.


*Feedback wanted!*

Now it is your turn: What do you think about my proposal? Should I continue
with my effort? Do you have ideas what can/should/must be improved? Would
the new system contradict anything in our policies that I'm not aware of?

I appreciate your feedback. I'm jandd in #sysadm on irc.cacert.org if you
want to discuss this more directly.


Best regards
Jan


[1] http://www.sphinx-doc.org/en/stable/
[2] http://git.cacert.org/gitweb/?p=cacert-infradocs.git
[3] https://mako.cc/writing/hill-free_tools.html
[4] https://jenkins.cacert.org/job/cacert-infradocs/
[5] 
https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/index.html
[6] 
https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/building.html
[7] http://dhruvasagar.com/2013/03/17/vim-table-mode
[8] https://pypi.python.org/pypi/jandd.sphinxext.ip
[9] 
https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/iplist.html
[10] 
https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/iplist.rst/*view*/
[11] 
https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/genindex.html
[12] 
https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/systems/board.html#local-modifications-to-openerp

-- 
Jan Dittberner - CAcert Infrastructure Team Lead
Software Architect, Debian Developer
GPG-key: 4096R/558FB8DD 2009-05-10
         B2FF 1D95 CE8F 7A22 DF4C  F09B A73E 0055 558F B8DD
https://jan.dittberner.info/

Attachment: smime.p7s
Description: S/MIME cryptographic signature