This wiki is obsolete, see the NorduGrid web pages for up to date information.

DocsProposal

From NorduGrid
Jump to navigationJump to search

2011-06-09 : Skype teleconf for planning

Next meeting is scheduled 2011-07-07 h13:00

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 ?


Next meeting is scheduled 2011-07-07 h13:00



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:

  1. Number of documents must be reduced. To do this, we need to restructure them avoiding repetitions.
  2. Documentation needs to be in html format for ease of access. This is a must for nowadays widespread connectivity, i.e. accessing via smartphones.
  3. Documents need to be in pdf format as they have to be printed or presented for projects as a proof of record.
  4. A consistent structure across documents is needed so to ease writer's work and cross referencing, avoiding rewriting the same stuff
  5. A document lifecycle on at least yearly basis must be defined so to have documentation up-to-date.

Discussion and decisions:

  1. Florido's proposal of merging docs reduces them from 59 to 16. Some have obsolete or incomprehensible information and need severe rewriting.
  2. Latex must be kept as most of ARC people is used to it and the building system is already in place on SVN.
  3. 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.
  4. 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:
    1. 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.
    2. 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.
  5. 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


Responsible:

  • Oxana


Users and System Administrator basic pre-installation requirements


Wil contain:

Assignee(s):

  • Oxana


- Developers Start Guide

Assignee(s)

  • Anders

- tutorials

Client


Responsible:

  • Martin Skou


- Users and System Administrators Clients deployment and usage guide.


Will contain:

Assignee(s):

  • Martin Skou
  • Jon
  • Zsombor
  • Jonas?


- Client developer handbook


Assignee(s):

  • Martin Skou
  • Jon

- tutorials

Computing Element


Responsible:

  • Florido


System Administrator CE Installation and configuration Manual


Will contain:

- System Administrator <specific component/middleware integration> and configuration guide :


will include:

Assignee(s):

  • Florido
  • Oxana
  • Balazs
  • Aleksandr
  • Adrian
  • Daniel
  • Anders
  • Weizhong
  • Gabor

- tutorials

- CE Developer handbook


Assignee(s)

  • Aleksandr
  • Daniel
  • Anders
  • Adrian
  • Gabor
  • Steffen
  • Thomas?
  • Samir?

- programming tutorials

Infosys

Responsible:

  • Mattias


-System Administrator IS Installation and configuration manual

Will include:

- specific component configuration guides (interaction with other middlewares or indexing services

  • some bdii howto?

Assignee(s)

  • Mattias
  • Balazs
  • Ivan
  • Gabor

- tutorials

- IS developer handbook


Assignee(s)

  • Mattias

- programming tutorials

Storage Element


Responsible:

  • David


System Administrator SE Installation and Configuration

Will contain:

Assignee(s)

  • David
  • Jon
  • Zsombor

- tutorials

- SE Developer handbook


Assignee(s)

  • David
  • Jon
  • Zsombor

- programming tutorials

Monitoring


Responsible:

  •  ?


- Using public monitors to find resources


  • Oxana

Will include:


System administrator monitoring tools instalation and configuration


Will include:

- separated manuals for specific monitoring tools such as Nagios


Assignees

  •  ?
  • Mattias

- tutorials

- ARC monitoring developer handbook


Assignees

  • Mattias

- programming tutorials