Slides on the IT- Slides on the IT- CDA Service CDA Service - - PowerPoint PPT Presentation
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
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 and in the MAlt context we propose the following documentation rationalisation. discussions and inventory
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 (made in Jekyll with Markdown) These are currently manually synchronised, hopefully automated in the future. the CDA web site
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: Written in Markdown with (which builds static HTML web sites with an easy configuration file). 1. Versioned and published via Gitlab 2. Hosted in a dedicated (EOS-based now, in OpenShift soon) web site. 3. See , including for above steps 1-3. MkDocs guidelines a boilerplate
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: Written in Markdown with (which builds static HTML web sites with an easy configuration file). 1. Versioned and published via Gitlab 2. Hosted in a dedicated (EOS-based now, in OpenShift soon) web site. 3. See links to guidelines in the last-but-one slide. MkDocs
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 for new services, with restrictions set, where appropriate. Discourse
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
Obtain Service Managers’ agreement on their Public Service Sites’ new format and location. A and are written to get help with the migration and the content validity. 1. Expand the use of Discourse to obtain enough data for its popularity and scalability. 2. Expand tools for 1 to Administration Guides. 3. Assign a curator for the Short General Description content maintenance and the development of the SNow-Jekyll sync. 4. TECH project STAG project
18
Pending actions Pending actions
SLs to discuss the proposed strategy in their sections. 1. 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. 2.
Background info Background info
in more words. Other recent reflection notes:
hosting. The first draft of this proposal IC section internal reflection Group-wide reflection Technical notes
19
Thank You! Thank You!
Lets discuss it!
20