Summer 2019 status:

• Redesign of the CDA general information (Jekyll) site services' page with Summer Student Timon Viola. Project https://it-student-projects.web.cern.ch/projects/malt-related-project-cda-jekyll-site-finalisation
  • 2019-07-24: Timon V. prompted CDA members to comment on new design of the CDA services' page in https://mattermost.web.cern.ch/it-dep/pl/tg6185ot87rhtfwm7c9mscwrno which is inspired from https://htmlreference.io/
  • 2019-07-25: Maria D. prompted CDA service managers to compare SNOW and Jekyll short descriptions in https://mattermost.web.cern.ch/it-dep/pl/1uctcmih37gw7rrs6kdt9sty3w
• General CDA Documentation strategy progress reports in https://codimd.web.cern.ch/J40rhuevQAqQ12oqNtgZ-g

Autumn 2018 status:

• Usability tests with eye-tracker (offered by Geneva University) done with 20 users for the CDA general information (Jekyll) site and Master's student stagiaire Maud Bernies in the period 2018.10.1-12. Details and final report linked from https://indico.cern.ch/event/760297/
• General CDA Documentation strategy presented to the CDA SLM on 2018-10-31. Details and slides in https://indico.cern.ch/event/769168/

Summer 2018 status:

• Check-point on 2018-08-23. See notes.
• Strategy draft for adoption here.
• Technical instructions for Markdown editing, gitlab publishing and EOS hosting here.

Beginning 2018 status:

• Check-point on 2018-01-10. See notes.
• In brief: Jekyll it is. Site begins. The question is How to write a UserStories-based navigation without overloading the pages or making endless chaotic clicks.

Autumn 2017 status:

• Check-point on 2017-10-25. See notes.
• CDAPublicDocTemplate contains all the details. The template for the entry page will have to be different. It will contain something like this but agnostic to organigramme acronyms. It should be shorter and prettier...
• Maria parsed all the Jekyll and Hugo themes for adoption/adjustment. Conclusions and notes in Comment on the Template page (2017-10-18 and later).
• Markdown is already the choice for most service managers. Example: the new indico user help doc, written in GitBook, but as it might stop being open-source, moved to MkDocs.
• Because our scope is CERN service pages, accessed by CERN users, gitlab is the place to publish.
• Jekyll will be tried in the pilot, due to its templates' offer. The Markdown policy is kept.

May 2017 brainstorming results:

CDA members' discussion

Introduction: Maria - Main contributors: Bruno, Emmanuel, Giacomo, Jose, Ludmila, Michal, Nikos, Pawel, Pedro, Pete, Ruben, Tibor, Tim,... Who and what do I forget?!

1. Focus: End-user documentation to start with.
2. Purpose: Present our services without organisational details that may change (e.g. No group/section names in file paths and URIs). Add the service strategy aspects that cover the future (e.g. which services will be discontinued/replaced by which, when).
3. Location: This is important! Prepare gitlab repositories for each of our services.
4. Edit tools: Use Markdown. Choose the variant of your preference to display your doc, most likely gitbook or jekyll (see why further down in this page).
5. Content structure guidelines: Emmanuel, Maria & Tim to make a CDAPublicDocTemplate for the service managers to start putting content on their services. Drafts will be published on https://test-cda.web.cern.ch/ for further discussion.
6. Existing documentation: Investigate the possibility for the use of Connectors that will feed our content into the SNOW KB and the IT web site. This new location will be shown from the IT organigramme and IT service pages. Our effort will give useful input for the future of the official CERN IT site. SNOW content structure is fixed, we can't change it. We work on updating the SNOW FE, SE, KB info (see this work in ICsectionDoc#CDA_internal_twikis_specific_to the twikis for notes on each CDA/IC service.
7. Candidate subjects for future brainstorming:
   • Do high-level user stories cross-group/cross-department (e.g. I am starting a new experiment, what do I need to set-up: indico, vidyo, cds, edms, e-groups,...) require the creation of a documentation curator role?
   • Do we harmonise the product description documentation (for peer developers)?
   • Do we re-visit the supporters' documentation? See the attachments of https://twiki.cern.ch/ELearning/UsersFeedback for use of SNOW KB articles.

What do we want to do:

• Base our documentation on User Stories. Project description in Document with the user in mind
• To do this, investigate technical ways not to be lost in navigation so that:
  • If a User Story is in existing documentation ==> point to the documentation.
  • If it isn't ==> write SNOW Knowledge Base articles.
  • Definitely think of services and not of the organigramme.
• Do not change the technology of existing documentation pages that also perform functions, e.g. mmm.cern.ch or account.cern.ch and/or are linked from many pages.
• Existing sharepoint documentation in espace.cern.ch should be kept while it is up-to-date because it has a nice gitbook-like layout. It doesn't handle versions, so it can't be recommended. Jekyll is a candidate replacement for these pages.
• For new docs and those who need to be re-done, adopt a variant of the Markdown language like:
  • gitbook is a natural choice for all the packages in github/gitlab (has a twiki-like look and maintains versions)
  • Jekyll, which "supports Markdown out of the box" is used e.g. by a new internal doc WF section site.
• Assemble information from our (past) presence in social
• Evolve Markdown-based site http://test-cda.web.cern.ch/ in the spirit of the project, i.e. with the user in mind.
• Put content in the IT official pages (empty till March 2017- Done, see below).

Investigation status Spring 2017

1. The obvious statement: There is no one-tool-fits-all-needs.
2. Web Frameworks (WF) (Brunos' input) adopted:
   1. Jekyll, for a new internal doc WF section site developed by Bruno. Its advantage (input by Pedro): it allows you to define different base templates for different content types.
   2. WF still uses their sharepoint site for project management tasks and for document sharing, e.g. .xls co-editing via the browser.
   3. In this sense, Jekyll is best for static information. All imports from SSB and other warnings related to projects or service status are implemented by Bruno.

CERN IT web site

Description	URI	New content from	Action what?	Action who?
CERN IT page about the CDA group	https://information-technology.web.cern.ch/about/organisation/collaboration-devices-applications	Group mandate in social, cern facebook etc	Add content. Nothing is there mid-March 2017	Maria D. Done.
CERN IT page about CDA-AD	https://information-technology.web.cern.ch/about/organisation/applications-devices	Michal sent section services .xls to Maria	Insert content - see originals attached to this twiki	Maria. Done with Michal's changes incorporated.
CERN IT page about CDA-DR	https://information-technology.web.cern.ch/about/organisation/digital-repositories	José explained what everyine in the test-cda web chart does in DR section	Insert content - see originals attached to this twiki	Maria. Done and José approved
CERN IT page about CDA-IC	https://information-technology.web.cern.ch/about/organisation/integrated-collaboration	Section services taken from social	Maria got edit permissions and wrote new candidate content. All ICsectionDoc with detailed sub-twikis	Discussed at the section meeting of Feb. 22nd 2017. Done.
CERN IT page about CDA-WF	https://information-technology.web.cern.ch/about/organisation/web-frameworks	Discussion with Andreas W. & IT service pages	list the section services in the organigramme	Maria with corrections by Andreas

Presentations

• E-learning and Documentation presentation to the ATLAS Software & Computing Documentation Workshop Slides,same slides, different web server, Agenda, Notes by Maria Dimou.

All our services

Page https://it-dep-cda.web.cern.ch/it-dep-cda/services/ is done in Jekyll based on IT-CDA members' votes with valuable help by Eduardo Alvares and Bruno de Sousa. Drawings made by Sara Reichlen in draw.io from comments on the "flower petals' original.

Bubbles v.3 - Most voted option more compact, i.e. less space between individual service bubbles.

Bubbles v.2 - bubbles flying in the air - services taken from the the official IT web site - CDA section.

Squares v.2 - less loaded page, as only the domains of our services are shown, still matching the look of our preferred Jekyll theme. NB! In this scenario, one more page will be needed, where all services per domain (e.g. all Windows' services) will be listed, i.e. page for ServiceX will be reached at the 4th click!

Squares v.1 - to match the look of our preferred Jekyll theme.

"Petales de fleur" v.1 Very first draft - services taken from the Nov. 2017 CDA group meeting.

Comments

   git log
   git branch
   git checkout master
   git branch -D maria
   git branch -D READMEupload 

-- MariaDimou - 2017-03-02