ASDF Slides on Documentation === --- The IT-CDA Service Documentation Choice === Maria Dimou IT-CDA-IC ASDF of 2019/03/14 [Event Details here]( --- ### Why CDA reflects on Documentation - _Users_ of our very visible and widely used services have very different backgrounds, so clarity and ease of navigation are important. - Today, these services are documented in various formats. - So far, we didn't have _a required agreed set of documentation types_ a service should have CDA-wide. - After discussions and inventory _and in the MAlt context_ we proposed a documentation rationalisation. --- ### Goal of this reflection To offer guidelines to service managers in order to ensure: - a common look and feel for all user-facing documentation. - that all service documentation is independent from a temporary administrative structure (group names & such acronyms). - that central tools are used whenever possible. - that publishing and maintaining this information is as easy and standardised as possible. - as little data redundancy as possible. --- ### Documentation types covered today We addressed all documentation types of CDA services. Today we present our choice for: - Public Service Site (including User Guides) - Administration Guide --- ### Public Service Site Accessible by all users of the given Service. To be: 1. Written in Markdown (we opted for [MkDocs]( which builds static HTML web sites with an easy configuration file). 1. Versioned and published via Gitlab 1. Hosted in a dedicated (EOS-based now, in OpenShift soon) web site. [Instructions]( --- ### Example of a Public Service Site [The Indico User Guide]( [![Service User Guide]( =700x)]( --- ### Administration Guide This is _for service managers' internal use_. It can be hosted on the same web site, as a sub-tree of the Public Service Site with access restrictions. Same choices: 1. Written in Markdown with [MkDocs]( 1. Versioned and published via Gitlab 1. Hosted in a dedicated (EOS-based now, in OpenShift soon) web site. [See here how to define restrictions]( --- ### Example of an Administration Guide [The Indico Ops Guide]( [![Service Administration Guide]( =700x)]( --- ### Links on how we got here * [Beginning of the reflection and inventory of existing CDA documentation pages]( * [Evaluations, comments and more]( * [CDA-internal discussion on all Documentation types]( * [Guidelines on how to get started]( containing: * Markdown basics, * MkDocs installation, * gitlab project creation for documentation, * web site registration in EOS (as per current situation). --- ### Thank You! Lets discuss it!