CAcert System Admins discussion list

[Jan Dittberner <jandd AT cacert.org>]

On Thu, May 05, 2016 at 11:00:30AM +0200, Wytze van der Raay wrote:
> Hi Jan,
> 
> On 05/03/2016 07:10 PM, Jan Dittberner wrote:
> > ...
> > 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].
> > ...
> > *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 think you have done some awesome work here! The CAcert systems 
> documentation
> in the wiki is suffering in many ways indeed, and this is not limited to
> infrastructure systems, it holds for critical systems too.

Thanks for your kind words of encouragement. So far I received positive
feedback from Mario, Benedikt and you and will continue this effort.

> So I'd like to encourage you not only to continue work with this new setup,
> but I'd also like to ask you to make it slightly more generic and include
> space for critical systems as well (obviously the task of filling that part
> falls onto the critical sysadmin team). Documentation-wise, there is no
> need for a strong separation between the two types of systems I'd say. And
> with little tools like your little IP address extension, more
> comprehensive results will be produced by having critical systems included
> too.

I'll create a skeleton for adding the critical systems. Maybe the file
systems/template.rst is a good base for documenting the critical systems
too. I'll put a copy of that template in a directory for the critical
systems that you can use as a starting point.

> Policy-wise, I am not aware of any requirement to use a specific system or
> protocol for our systems and procedures documentation, it's only the quality
> that counts I'd say.

Sounds good. I'll create some canonical place on webstatic where Jenkins can
publish the generated documentation. I'll write a corresponding DNS setup
request in a separate mail to the DNS admin address. When this is in place
and integrated with Jenkins I'll add pointers to the new documentation in
the existing Wiki pages.

> I guess we need to start learning RST now.
> Do you have any good pointers for that?

The tutorials for Sphinx [1] and the Restructured Text Primer [2] should be
good starting points.

[1] http://www.sphinx-doc.org/en/stable/tutorial.html
[2] http://www.sphinx-doc.org/en/stable/rest.html#rst-primer

> Thanks again for your efforts in getting this innovation started!

You're welcome, thanks for the feedback.


Best regards
Jan

-- 
Jan Dittberner - CAcert Infrastructure Team
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