Slides on the IT-CDA Service Documentation Strategy === Thomas Baron & Maria Dimou --- ### This presentation - Summarises a proposal on: - the types of documentation every Service needs to have and - where each of these documentation types should be hosted. - Suggests some implementation steps. [As agreed with the CDA SLs on 2018/10/31](https://indico.cern.ch/event/769168/) and [reviewed on 2019/01/24](https://indico.cern.ch/event/787521/) --- ### Reasons for this Proposal - Our Group runs very visible and widely used services. - These services are documented in various formats. - So far, we didn't have an agreed set of sine qua non documentation types a service should have. - After [discussions and inventory](https://twiki.cern.ch/CDAgroup/CDAPublicDoc) _and_ in the MAlt context we propose the following documentation rationalisation. --- ### Goal of this Proposal To offer guidelines to our service managers in order to ensure: - a common look and feel for all user-facing documentation of CDA services - that all service documentation is independent from a temporary administrative structure - 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 --- ### Proposed Documentation Types We are proposing a common look and feel for all documentation types of CDA services. Documentation types covered are: - Short General Service Description - Public Service Site (including User Guides) - Administration Guide - FAQs for users Service Incidents/Requests/Changes/Privacy_Notices are also covered for completeness without proposing changes. --- ### Short General Service Description It should live in: - The SNow FE/SE Description and - The relevant service page of [the CDA web site](https://cern.ch/it-dep-cda/services/) (made in Jekyll with Markdown) These are currently manually synchronised, hopefully automated in the future. --- ### Example of short service description in SNow [](https://cern.service-now.com/service-portal/service-element.do?name=Indico-Service) --- ### Example of short service description in the CDA site  --- ### Public Service Site Accessible by all users of the given Service. To be: 1. Written in Markdown with [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. See [guidelines](https://twiki.cern.ch/Edutech/ServiceDocumentationGuidelines), including [a boilerplate](https://gitlab.cern.ch/it-dep-cda/docs-boilerplate) for above steps 1-3. --- ### 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 should be hosted on the same web site, as a restricted sub-tree of the Public Service Site. To be: 1. Written in Markdown with [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. See links to guidelines in the last-but-one slide. --- ### 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/) --- ### FAQs for users &/or Administrators/Supporters - In use today: - SNow KBs are the ones Level 1,2 supporters agree to use - Sections with restricted access rights in the Public or Administration Guides. - We recommend the inclusion of FAQs in the Public Service Site (Markdown) for **new services**, with restrictions set, where appropriate. There will be a link to this location from the SNow. --- ### Example of a Service FAQ in SNOW KBs today [](https://cern.service-now.com/service-portal/faq.do?se=Indico-Service) --- ### Discussion Forum We recommend the use of [Discourse](https://discourse.web.cern.ch/) for **new services**, with restrictions set, where appropriate. --- ### Service Incidents/Changes All CDA **Service Incidents/Changes** live in SNow SSB, **right?** [](https://cern.service-now.com/service-portal/ssb.do?area=IT) --- ### Service Change Requests These are tracked in either Github/Gitlab Issues or Jira tickets, and entered either directly or through SNow requests. The Indico example: [](https://github.com/indico/indico/issues) --- ### Privacy Notice This lives in SNow and is _mandatory_ for all services. --- ### Implementation 1. Obtain Service Managers' agreement on their **Public Service Sites**' new format and location. A [TECH project](https://it-student-projects.web.cern.ch/projects/malt-related-project-standard-documentation-workflow-and-conversion-tools-documentation) and [STAG project](https://it-student-projects.web.cern.ch/projects/malt-related-project-new-documentation-testing-dateness-and-functionality) are written to get help with the migration and the content validity. 2. Expand the use of Discourse to obtain enough data for its popularity and scalability. 3. Expand tools for 1 to **Administration Guides**. 4. Assign a curator for the **Short General Description** _content maintenance_ and the _development_ of the SNow-Jekyll sync. --- ### Pending actions 1. SLs to **discuss the proposed strategy** in their sections. 2. Get suggestions and, finally, a consensus on the **naming convention** for CDA Service Documentation, before the _templates_ are defined in OpenShift for all Service Public Sites, Administration sub-sites and discourse fora names. ### Background info - [The first draft of this proposal](https://codimd.web.cern.ch/s/S1r2wlnUQ#) in more words. Other recent reflection notes: - [IC section internal reflection](https://codimd.web.cern.ch/s/rJXzcvzem#) - [Group-wide reflection](https://twiki.cern.ch/CDAgroup/CDAPublicDoc) - [Technical notes](https://twiki.cern.ch/Edutech/ServiceDocumentationGuidelines) on Markdown editing, gitlab publishing and EOS hosting. --- ### Thank You! Lets discuss it!