perfsonar development work

[Jochen Reinwand <>]

Hi all,

Using Word documents for documenting OpenSource software is a really bad idea 
I think! Why not use something more common like DocBook?
It was designed especially for documenting software and can produce a lot of 
different documents like html and pdf.

regards,
Jochen

On Tuesday 19 December 2006 12:50, Matthias K. Hamm wrote:
> Hi Szymon,
>
> just a few suggestions:
>
> (*) intendation of  whole paragraphs should not be used too much. This
> applies especially to the metadata description document at the section
> explaining the XML structure. Personally, I think it is easier to read
> if the text is left bound. The structure of the XML should be clear by
> the numbering of the headings. As an example I attached the document for
> E2Emon.
>
> (*) I do not know how much of the perfSONAR people actually use Word to
> edit the files (we do ;-) ). In this case, Word has handy features to
> provide format templates. In the RelMgmt templates, it would be helpful
> if pre-defined formats are used with names like "XML-Entity
> description". To be sure, the text in the template could give advice
> which of the formats to use in which section.
>
> (*) Personally, I like if long text passages are separated from the
> text, e.g. by giving them a light-grey background. Perhaps we could add
> this feature to the templates (nice to have ;-) )
>
> Cheers,
>
> M&M
>
> Szymon Trocha schrieb:
> > Matthias K. Hamm wrote:
> >> Hi,
> >>
> >> after editing the perfSONAR Rel. Mgmt. documents for E2Emon, we have
> >> some suggestions how the document set could be improved in the future:
> >>
> >> (*) we recommend decreasing the number of files. Especially the files
> >> "functional specification" and "interface specification" could be
> >> merged, same applies to "installation targets" and "samples for
> >> configuration files". This would also decrease the need for
> >> references between documents..
> >> (*) the formats and document structure are not always handy.
> >> Especially the "interface specification" and the "metadata file
> >> specfication" with it`s complex XML description sections demand a
> >> easy-to-use format. We have adopted and slightly changed the
> >> RRD-MA-Example, but this could be improved for better readability, too.
> >
> > Hi Matthias,
> >
> > Thank you for your valuable comments. As regards the format of
> > specifications do you have any proposals in mind what can be changed
> > to improve readability?
> >
> > regards,

-- 
Jochen Reinwand                                 Tel: +49 9131 852-8689
DFN Labor

Regionales Rechenzentrum Erlangen
Martensstrasse 1
91058 Erlangen
 
email: