Summer 2019 status:

Autumn 2018 status:

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 on Documenting with the user in mind.

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:
  • 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

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

Attachments to this twiki show the pages (empty) mid-March 2017. The IC section has more details starting from ICsectionDoc.

-- Maria Dimou - 2017-03-20

There a mix of links under CERN IT pages on services, sometimes the service entry point, sometimes the SNOW SE. I vote for the first one.

-- Maria Dimou - 2017-03-20

The CERN IT pages on services, themselves, sometimes go to the homepage of a given service with no intermediate description. I think this is good, as there is one less thing to maintain.

-- Maria Dimou - 2017-04-04

A valid twiki User Story:

This page is large. If you make PDF, it is chopped on the right. Workaround by Pete Jones:

After pressing on the "PDF" button, append ?pdforientation=landscape

to get https://twiki.cern.ch/twiki/bin/genpdf/CDAgroup/CDAPublicDoc?pdforientation=landscape

-- Maria Dimou - 2017-04-06

Novice gitlab user notes

Better version in https://gitlab.cern.ch/it-dep-cda/public-website/blob/master/CONTRIBUTING.txt

Markdown for beginners

Random notes to start with jekyll and gitlab:

Maria uses "atom" on ubuntu.

How to clone the published version from gitlab to the local folder (requires CERN login) from the command line: cd ~/CDA/it-dep-cda (local folder name)

git clone ssh://git@gitlab.cern.ch:7999/git-group/git-project.git

To avoid typing the login/passwd everytime better register your ssh public key with gitlab and use another command. This is how to find the key text to copy/paste and the SSH-based URI to clone: cat ~/.ssh/id_rsa.pub git fetch git remote set-url origin ssh://git@gitlab.cern.ch:7999/it-dep-cda/public-website.git

open local folder public-website with the atom editor

chk publishing activity via the gitlab CI/CD -- pipelines left banner tab from https://gitlab.cern.ch/it-dep-cda/public-website/

Published version https://it-dep-cda.web.cern.ch/

Publishing process:

  1. save (local in editor)
  2. stage (local in project)
  3. define new branch name from within your editor
  4. commit (with a msg)
  5. push (branch name will be created at the gitlab destination project, if it doesn't exist)
  6. you may now review your changes via URI http://it-dep-cda.web.cern.ch/it-dep-cda/review/<_yourbranchname_>/<_path-to-the-page-you-changed>
  7. create merge request, if happy with the changes.

if one doesn't see in the editor changes made locally pending for stage,commit,push ==> git status from the terminal command line.

if one makes a private branch, to avoid staging straight to the master, one must make a merge request after the build passed. example.

if one wants to preview the .md edits without having to wait for gitlab upload to complete, one can use the URI http://it-dep-cda.web.cern.ch/it-dep-cda/review/<_yourbranchname_>/<_path-to-the-page-you-changed>

To delete a local private branch type from the command line:

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

-- Maria Dimou - 2017-10-18

-- MariaDimou - 2017-03-02

Topic attachments
I Attachment History Action Size Date Who Comment
PDFpdf CDAgroup_CDAPublicDoc.pdf r1 manage 584.7 K 2017-04-06 - 12:11 MariaDimou 2017.04.06 status of this page
PDFpdf CERNEvaluation.pdf r1 manage 570.7 K 2017-08-01 - 13:57 MariaDimou CERN web site evaluation made by the "Information Science" dept. of HESGE La Battelle Prof. R.Schneider
PDFpdf Cuche_DossierTP.pdf r1 manage 3745.1 K 2018-06-11 - 18:21 MariaDimou Evaluation by HESGE Information Science students of Professor Rene' Schneider - assistant Julien Raemy
PDFpdf Dossier_CERN_-_SaraLagare.pdf r1 manage 1753.0 K 2018-06-11 - 18:21 MariaDimou Evaluation by HESGE Information Science students of Professor Rene' Schneider - assistant Julien Raemy
PNGpng IT-CDA-DR-2017-03-30.png r1 manage 162.1 K 2017-03-30 - 17:48 MariaDimou IT organigramme page on CDA-DR on 20170330
PNGpng IT-CDA-WF-2017-03-20.png r1 manage 158.5 K 2017-03-20 - 15:02 MariaDimou IT organigramme page on CDA-WF on 20170320
PNGpng IT-CDA-public-web-pages-20170313.png r1 manage 201.1 K 2017-03-14 - 14:49 MariaDimou IT organigramme page on CDA on 20170313
PNGpng IT-CDA_Bubbles-v.2.png r1 manage 246.0 K 2017-11-20 - 12:55 MariaDimou All our services - Bubbles-v.2 by Sara Reichlen
PNGpng IT-CDA_Bubbles-v.3.png r1 manage 263.5 K 2017-11-20 - 12:41 MariaDimou All our services - Bubbles-v.3 by Sara Reichlen
PNGpng IT-CDA_Petales.png r1 manage 117.2 K 2017-11-15 - 11:12 MariaDimou all our services - v.1 drawn by Sara Reichlen.
PNGpng IT-CDA_Squares-allin1_v.1.png r1 manage 143.5 K 2017-11-20 - 14:56 MariaDimou All our services - Squares v.1 by Sara Reichlen - to match the 'jekyll feeling responsive' theme we selected
PNGpng IT-CDA_Squares_v.2_level1.png r1 manage 73.3 K 2017-11-20 - 14:57 MariaDimou All our services - Squares v.2 by Sara Reichlen - grouped by domain, i.e. one more page required for all details per domain!
PNGpng IT-CDS-AD-2017-03-30.png r1 manage 168.7 K 2017-03-30 - 17:49 MariaDimou IT organigramme page on CDA-AD on 20170330
Unknown file formatodt ITCDA_regroupementServices.odt r1 manage 19.0 K 2017-11-15 - 11:46 MariaDimou All CDA services - listed by Sara Reichlen based on the official IT (about us tab) pages.
PNGpng J_Price_book_cover.png r1 manage 519.3 K 2017-04-25 - 13:22 MariaDimou  
Unknown file formatdocx Manivanh-UCD_Dossier.docx r1 manage 1262.9 K 2018-06-11 - 18:21 MariaDimou Evaluation by HESGE Information Science students of Professor Rene' Schneider - assistant Julien Raemy
PDFpdf ergonomie_reichlen_.pdf r1 manage 1962.6 K 2018-06-11 - 18:21 MariaDimou Evaluation by HESGE Information Science students of Professor Rene' Schneider - assistant Julien Raemy
PDFpdf ku_philippe_dossier_cern.pdf r1 manage 8189.6 K 2018-06-11 - 18:21 MariaDimou Evaluation by HESGE Information Science students of Professor Rene' Schneider - assistant Julien Raemy
Edit | Attach | Watch | Print version | History: r51 < r50 < r49 < r48 < r47 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r51 - 2019-07-25 - MariaDimou
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CDAgroup All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright &© 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback