--- ## **Documentation services** <br /> <br /> <br /> Eduardo Alvarez Fernandez #### **IT-CDA-WF** --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **What is different on documentation websites** - Different workflow - Validation & Revisions - Contributed, sometimes realtime - Search driven readability - Focus on content, format/layout as secondary factor  --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **Central services** - Multiples alternatives in parallel - Selection depends on your: - use case - feature requirements - familiarity with the tool --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **TWiki** - Many years of experience at CERN - Wiki syntax, with WYSIWYG - Strong document structure and navigation - Still a very good option for documentation - Options are being investigated to modernize the tool --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **TWiki** | web name | topics | attachments | topics accessed in 2019 | | ------------- |:-------------:| ------------:| --------------:| | LHCbPhysics | 2340 | 22100 | 98669 | | LHCb | 3064 | 8940 | 502911 | | LHCbInternal | 90 | 390 | 3338 | --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **SharePoint** - Microsoft licenced software - Central service to be decomissioned ([Malt project](https://malt.web.cern.ch)) - Alternative solutions based on use cases - SharePoint 365 for users that still require the tool --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **Drupal** - Content Management System - Highly customizable, but also more complex for beginners - Based on core Book module, [https://www.drupal.org/docs/8/core/modules/book/overview](https://www.drupal.org/docs/8/core/modules/book/overview) - Theming --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **Drupal**  --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **MkDocs** - Use case driven tool - Based on project [MkDocs](https://www.mkdocs.org/) - Markdown syntax language / Portability - Based on git workflows / Automatize - Multiple environments - Other advance use cases will be covered, based on user feedback - Simple authorization options - Starting guide: [https://how-to.docs.cern.ch/](https://how-to.docs.cern.ch/) --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **MkDocs**  --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **Discourse** - Forum like software - Allow conversation driven/collaborative documentation - Creation request: [https://cern.service-now.com/service-portal/service-element.do?name=discourse](https://cern.service-now.com/service-portal/service-element.do?name=discourse) - [https://discourse.web.cern.ch/](https://discourse.web.cern.ch/) --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **Discourse**  --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **Wordpress** - Easy blogging experience - Initially offered as Openshift template - **Prototype status**, production for 2020 - [https://gitlab.cern.ch/wordpress/wordpress-quickstart](https://gitlab.cern.ch/wordpress/wordpress-quickstart) --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> ### **Wordpress**  --- ### **Best fit tool table** | Use case | Technology | status | | ------------- |:-------------:| ------------:| | Documentation website | **MkDocs** | Production Openshift template | | Forum/community webapp | Discourse | Production | | Blog | Wordpress | Pilot Openshift template | | Complex documentation | Twiki \| Drupal | Production | --- ### **Summary** - MkDocs, preferably and official documentation service - Twiki and Drupal as alternatives if more complex requirements are needed - Discourse for forum like / community functionality - ***.docs.cern.ch** domain available for better documentation discovery - Extra tools for your toolbox: - Codimd [https://codimd.web.cern.ch](https://codimd.web.cern.ch), realtime editing, presentations, quick notes --- <!-- .slide: data-background="https://codimd.web.cern.ch/uploads/upload_6878d23cd09a4261c4a478bc7b8eb35b.jpg" data-background-opacity=".2" --> # **Thanks** --- Background image from cds.cern.ch