[OpenSER-Docs] First Clean-up Patch for Documentation

[Edson]

Hi, Daniel... Guys...

So let's try to draw a first to-do list, so that the work can begin...

1- Migrate the existing DOCs from SGML to XML format:
   I'm not a DocBook expert but Henning and I already changed some thoughts
   on this. What's not clear to me is if this is just a translation matter
   or also a diagramatic problem? Translation is some kind of direct work,
   while diagramatic requires a previous discussion.

2- Suppress and/or Agregate new DOCs:
   Clean-up empty files (with a sort of "no content") is require, since
   there information can be gatered elsewhere, but agregate new DOCs is
   a sort of "asking for problems" approach, so I would say that some
   skeleton/template has to be defined. This has to become before this
   agregation issue. But this arises a problem: wich is the best 'skeleton'?
   Which kind of documentation will be present? How to automate it?

So this two points brings:
1- Documentation structure Skeleton/Template;
2- Documents Skeleton/Template defining chapter and, maybe, minimum section
   contents, definition of origin (directly from code? From Doxygen?) and,
   most important, responsibilities;
3- XML Style that translate/implement this skeleton/templates;
4- Conversion of actual SGML format to some DocBook-XML format;

Each of this points should define a milestone by itself and its end it could
be marked with IRC meeting where the results could be presented and
discussed.

Please these are only thoughs... so fell free to add more points and/or
point me wrongs approaches.

Edson

>-----Original Message-----
>From: Daniel-Constantin Mierla [mailto:miconda at gmail.com]
>Sent: terça-feira, 26 de fevereiro de 2008 18:37
>To: Edson
>Cc: openser-docs at lists.openser.org
>Subject: Re: [OpenSER-Docs] First Clean-up Patch for Documentation
>
>Hello,
>
>On 02/26/08 22:27, Edson wrote:
>> Hi, Guys...
>>
>> I finish the first clean-up of the documentation. It consisted by:
>> 1) remove all FAQ and DEVEL files considered empty in content (no content
>>    at all or just the default lines);
>> 2) remove of the <RevHistory>/</RevHistory> tag (and of course anything
>>    Between them);
>> 3) remove the comments at the EOF that beginned with
>>    "<!-- Keep this element at the end of the file";
>>
>Thanks, I believe we should think also the context of migrating to xml
>format. Anybody with some docbook xml experience? Hints, tips? I am
>investigating now the best way to migrate from sgml to xml.
>
>If we are going to remove some file, add new ones, we need to have in
>mind the near future as well.
>> The attached file (in ZIP format) is the resulting SVN DIFF file. It was
>> applied over trunk version, revision 3761.
>>
>> I would like to ask the developers how much is a good time to wait for
>> comments and revisions before commiting the changes? 1 week? 10 days?
>> Sugestions?
>>
>Let's plan kind of to-do list/roadmap, to sync the work and check the
>milestones. Otherwise many will work on same task, or go totally
>different direction.
>
>Cheers,
>Daniel
>
>> Edson
>>
>> ------------------------------------------------------------------------
>>
>> _______________________________________________
>> Openser-docs mailing list
>> Openser-docs at lists.openser.org
>> http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
>>