Slides on the IT- Slides on the IT- CDA Service CDA Service Documentation Documentation Strategy Strategy Thomas Baron & Maria Dimou As agreed with the CDA SLs on 2018/10/31 1
This presentation 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. 2
Reasons for this Proposal 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 and in the MAlt context we propose the following documentation rationalisation. 3
Goal of this Proposal 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 4
Proposed Documentation Types 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. 5
Short General Service Description Short General Service Description It should live in: The SNow FE/SE Description and The relevant service page of the CDA web site (made in Jekyll with Markdown) These are currently manually synchronised, hopefully automated in the future. 6
Example of short service description in SNow Example of short service description in SNow 7
Example of short service description in the Example of short service description in the CDA site CDA site 8
Public Service Site Public Service Site Accessible by all users of the given Service. To be: 1. Written in Markdown with MkDocs (which builds static HTML web sites with an easy configuration file). 2. Versioned and published via Gitlab 3. Hosted in a dedicated (EOS-based now, in OpenShift soon) web site. See guidelines , including a boilerplate for above steps 1-3. 9
Example of a Public Service Site Example of a Public Service Site The Indico User Guide 10
Administration Guide 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 (which builds static HTML web sites with an easy configuration file). 2. Versioned and published via Gitlab 3. Hosted in a dedicated (EOS-based now, in OpenShift soon) web site. See links to guidelines in the last-but-one slide. 11
Example of an Administration Guide Example of an Administration Guide The Indico Ops Guide . 12
FAQs for users &/or FAQs for users &/or Administrators/Supporters 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 use of Discourse for new services , with restrictions set, where appropriate. 13
Example of a Service FAQ in SNOW KBs Example of a Service FAQ in SNOW KBs today today 14
Service Incidents/Changes Service Incidents/Changes All CDA Service Incidents/Changes live in SNow SSB, right? 15
Service Change Requests 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: 16
Privacy Notice Privacy Notice This lives in SNow and is mandatory for all services. 17
Implementation Implementation 1. Obtain Service Managers’ agreement on their Public Service Sites ’ new format and location. A TECH project and STAG project 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. 18
Pending actions 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 Background info The first draft of this proposal in more words. Other recent reflection notes: IC section internal reflection Group-wide reflection Technical notes on Markdown editing, gitlab publishing and EOS hosting. 19
Thank You! Thank You! Lets discuss it! 20
Recommend
More recommend
