ASDF Slides on Documentation === --- The IT-CDA Service Documentation Choice === Maria Dimou IT-CDA-IC ASDF of 2019/03/14 [Event Details here](https://indico.cern.ch/event/800408/) --- ### 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](https://www.mkdocs.org) 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](https://twiki.cern.ch/Edutech/ServiceDocumentationGuidelines) --- ### Example of a Public Service Site [The Indico User Guide](https://indico-user-docs.web.cern.ch/indico-user-docs/) [](https://indico-user-docs.web.cern.ch/indico-user-docs/) --- ### 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](https://www.mkdocs.org). 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](https://twiki.cern.ch/Edutech/ServiceDocumentationGuidelines#Restricting_a_sub_directory_in_G) --- ### Example of an Administration Guide [The Indico Ops Guide](https://indico-ops.web.cern.ch/indico-ops/). [](https://indico-ops.web.cern.ch/indico-ops/) --- ### Links on how we got here * [Beginning of the reflection and inventory of existing CDA documentation pages](https://twiki.cern.ch/CDAgroup/CDAPublicDoc) * [Evaluations, comments and more](https://twiki.cern.ch/CDAgroup/CDAPublicDocTemplate) * [CDA-internal discussion on all Documentation types](https://codimd.web.cern.ch/p/Hy3SjYE2X#/) * [Guidelines on how to get started](https://twiki.cern.ch/Edutech/ServiceDocumentationGuidelines) containing: * Markdown basics, * MkDocs installation, * gitlab project creation for documentation, * web site registration in EOS (as per current situation). --- ### Thank You! Lets discuss it!