This wiki is obsolete, see the NorduGrid web pages for up to date information.
DocsProposal
2011-06-09 : Skype teleconf for planning
Participants: Florido, Zsombor, Oxana, Ivan, Jon
Common agreements:
- Some documents needs to be preserved for records. Cannot be renamed or moved.
- We will only apply new naming and new rules to new documentation.
- During this restructuring we will keep using latex in a way that docs can be built anywhere.
Objective:
Write the sysadmin guide as a proof of concept for the new documentation. This guide should have some graphics, easy access to items,will be published both in pdf and in html. Eventually it will be followed by a quick start guide.
Tasks:
1a) We need to give the reader a clear view of the ARC software. Zsombor will create a picture that summarizes things on a big scale. Will share it with us to cross-ckeck Due June 23
1b) Florido will divide the Sysadmin guide in three parts, will create an area for the overview. and make a structure according to that. Due June 23
1c) Ivan will have a look at latex2html and see how we can get good html pages out of latex. Objectives are to understand how much can we change of the URLs, how can we do crosslinking between documents, how can the process be automatized. Due 7th July
1d) everybody searches for some schema for the URLs. Oxana highlights that release number is not the same as document versioning. Due 7th July
Some proposed ones: [2:45:54 PM CEST] Zsombor Nagy:docs.nordugrid.org/11.05/a-rex/install [2:46:54 PM CEST] Florido Paganelli: docs.nordugrid.org/11.05/ARCCESysAdminGuide [2:47:44 PM CEST] Florido Paganelli: docs.nordugrid.org/11.05/ClientGuide [2:48:09 PM CEST] Zsombor Nagy: docs.nordugrid.org/11.05/ClientGuide/ClientGuide11.05.pdf [2:48:16 PM CEST] Zsombor Nagy: docs.nordugrid.org/11.05/ClientGuide/ClientGuide11.05.html [2:48:21 PM CEST] Zsombor Nagy: docs.nordugrid.org/11.05/ClientGuide/ClientGuide11.05.txt [2:50:06 PM CEST] Florido Paganelli: docs.nordugrid.org/11.05/ClientGuides/xxxx.pdf [2:50:58 PM CEST] Florido Paganelli: docs.nordugrid.org/11.05/DeverlopersGuide/ARCSE/tutorials [2:52:03 PM CEST] Márton Iván: docs.nordugrid.org/11.05/[tutorial|api|reference|howto|manual]/[client/developer/admin]/xxx.pdf [2:57:51 PM CEST] Florido Paganelli: docs.nordugrid.org/11.05/ARCCE/DevelopersGuide.html#CONFIGURATION [2:58:04 PM CEST] Márton Iván: docs.nordugrid.org/11.05/[client/developer/admin]/[tutorial|api|reference|howto|manual]/[component_name].[ext] [3:00:10 PM CEST] Florido Paganelli: docs.nordugrid.org/11.05/document#section
Sometimes documents can be for sysamins and clients, sometimes they are both manuals and papers, so we should try not to enforce everything in the URLs. Keep in mind that the URLs is mostly for us to write the documentation and for users to browse documentation quickly-- doesn't have to carry more than this.
2) Zsombor and Florido will agree on a structure so to have a picture to address sysadmins thru the different parts of the sysadmin document - Due 1 July
3) Florido will slice the document and assign missing documentation items for the CE to people. Due ?
2011-06-01 : Meeting during EMI AHM in Lund
This documentation warmup meeting was intended to brainstorm about the current documentation situation and comment on Florido's proposal for documentation restructuring.
Participants: Florido, Zsombor, Ivan, Jon, Mattias, Martin Skou
Hightlights of the discussion is as follows:
- Number of documents must be reduced. To do this, we need to restructure them avoiding repetitions.
- Documentation needs to be in html format for ease of access. This is a must for nowadays widespread connectivity, i.e. accessing via smartphones.
- Documents need to be in pdf format as they have to be printed or presented for projects as a proof of record.
- A consistent structure across documents is needed so to ease writer's work and cross referencing, avoiding rewriting the same stuff
- A document lifecycle on at least yearly basis must be defined so to have documentation up-to-date.
Discussion and decisions:
- Florido's proposal of merging docs reduces them from 59 to 16. Some have obsolete or incomprehensible information and need severe rewriting.
- Latex must be kept as most of ARC people is used to it and the building system is already in place on SVN.
- HTML documentation: Means of translating stuff via latex2html must be investigated. Python documentation is a good example of the other way around, from html to pdf. How easy is to write such documents? this needs investigation. Tools othen than latex exist such as markdown[1] but for the moment we stick to latex.
- we need to find a good numbering, chapters naming and linking logic between documents and within documents itself so that is easy to find information and refer to it. Some ideas:
- For the documentation to be up-to-date, documentation writing should follow at least major releases. For this reason somewhere in the links we should keep release version.
- Chapters naming and numbering should be at best consistent on each document, i.e. each document has Installation, Configuration... eventually we can refer to another document not to rewrite stuff.
- Document lifecycle should have a checkpoint each 6 months and a yearly checkpoint. Major documentation revision should precede major releases as a part of the releasing itself.
Documentation Proposal
Date changed: 2011-06-01
the working document that leads to these conclusions is this one: Media:Documentation_Proposal.odt
a color version of this table can be found here: Media:SummaryTable.odt
bold text identifies a single document.
Asset:
- A person is responsible for each area. (See Area column )
- A reviewer is assigned to each area. (to be decided. I would suggest the resposible chooses)
- The area responsible assigns subtasks to fill/wite part of the documentation to developers and reviewer.
| User type | User | Sysadmin | Developer |
| Area | |||
| Common:- Security
- Tools - Defs
|
Users and System Administrator basic pre-installation requirements
Assignee(s):
|
- Developers Start Guide
Assignee(s)
- tutorials | |
| Client
|
- Users and System Administrators Clients deployment and usage guide.
Assignee(s):
|
- Client developer handbook
Assignee(s):
- tutorials | |
| Computing Element
|
System Administrator CE Installation and configuration Manual
- System Administrator <specific component/middleware integration> and configuration guide :
Assignee(s):
- tutorials |
- CE Developer handbook
Assignee(s)
- programming tutorials | |
| Infosys
Responsible:
|
-System Administrator IS Installation and configuration manual
Will include:
- specific component configuration guides (interaction with other middlewares or indexing services
Assignee(s)
- tutorials |
- IS developer handbook
- programming tutorials | |
| Storage Element
|
System Administrator SE Installation and Configuration
Will contain:
Assignee(s)
- tutorials |
- SE Developer handbook
Assignee(s)
- programming tutorials | |
| Monitoring
|
- Using public monitors to find resources
Will include:
|
System administrator monitoring tools instalation and configuration
- separated manuals for specific monitoring tools such as Nagios
- tutorials |
- ARC monitoring developer handbook
- programming tutorials |
