Can it be clarified where community authored EOS documentation should be contributed to?
It would be great for the EOS tips being shared here to be curated into published docs which the community can help expand and update. Ideally accessible through the same auth accounts as used here.
Sources I am aware of:
http://eos-docs.web.cern.ch/eos-docs/
https://twiki.cern.ch/twiki/bin/view/EOS/
https://alien.web.cern.ch/content/documentation/howto/site/eosinstallation
…various site documentation sources
I would suggest the gitlab/github + Gitbook workflow as used to publish the Cernbox docs and CERN’s cloud docs, e.g https://clouddocs.web.cern.ch/clouddocs/ be considered as a method to fairly easily allow contributions to, and a review system for, community contributed docs.
Some advantages are git version control and community workflow engagement (branching, merge requests, assigned reviewers, etc.) onto of which Gitbook adds a user facing presentation layer.
We use this system and recently added some simple CI which, on each merge request, automatically deploys the new content into a freshly published gitbook, so reviewers can see how it will be rendered before accepting. We created a tutorial on using the Atom editor with its integrated git support to checkout a repo or branch, make edits and merge request them to help our team use this workflow.
Users can use any editing environments / git integrations they like - vim, eclipse, Atom, etc.
After evaluating various solutions to our document delimma, our team choose to go with a gitlab + gitbook based workflow. A brief summary of main factors we looked at, and why we went with this solution is shared below.
Cheers,
Pete
Why use gitlab?
Over many iterations of team discussion on what to use for user documentation many options were explored, some of which included:
-
Wordpress / Wiki / CMS
- Ties content to the framework, embedded in database
- Prevents user contribution
- Difficult review / approval workflow
- Search capabilities often poor
-
Git Repo / Wiki
- Separates content from website framework
- Provides ability for user to contribute
- Robust review / acceptance system
- Provides issue tracker
- However, directly rendered markdown is less than exciting
-
Enter Gitbook
- Enables git based workflow
- Enhances presentation layer, improved user experience
- Decent search capabilities
- User also able to git clone and grep, etc.
- Plugins provide extensibility (generating .pdfs, themes, etc.)
- If we move to a different web/documentation framework all existing docs are in git and .md format