[ic] Helping with the new documentation

Davor Ocelic docelic at mail.inet.hr
Mon Apr 3 13:07:31 EDT 2006


Hello everyone,

* Read this if you are interested in helping with the new documentation (in any
* way - including submitting your code and examples), or want to know more about
* xmldocs design and direction.


Table of contents:

[0] - introduction
[1] - getting in
[2] - contributing, but without learning the workings of xmldocs
[3] - contributing, with learning the workings of xmldocs
[4] - xmldocs history


[0]: Introduction

This email should lower the entry barrier and allow you to contribute
to Interchange documentation (xmldocs) without learning its structure
and devoting noticeable time to it in your daily routine. (Even though
it would be ideal if you did just that ;-)

We are so willing to accept user contributions that we encourage
any kind of input even if, for example, the documentation you send 
is unformatted, or the examples only work in your custom setup.
We'll fix everything, properly format it and integrate as appropriate.


[1]: Getting in

Subscribe to the 'docs' mailing list:

  http://www.icdevgroup.org/mailman/listinfo/docs 

Use the mailing list to:

 - stay informed about the events

 - post all your questions regarding documentation

 - submit your work, until you submit enough that we give you
   direct CVS commit privileges


[2]: Contributing, but without learning the workings of xmldocs

 1. Submit your documentation snippets (that you made for yourself
    or someone else, but they generically apply to Interchange),
    in any format

 2. Submit your examples (that you keep as reference examples or 
    have as working code in your setups),
    in any format

 3. Update/correct existing documentation or examples

 4. Write new documentation or examples,
    in any format

 5. Clean, sort and summarize useful -users mailing list posts for
    inclusion in the documentation,
    in any format

 6. Promote Interchange on your site
    http://www.icdevgroup.org/i/dev/logos


[3]: Contributing, with learning the workings of xmldocs

To become familiar with xmldocs internals, read our usual "Documentation"
page, especially from section "Building documentation from source" onwards.
Follow given pointers for additional reading on both pages given.

  http://www.icdevgroup.org/i/dev/docs
  http://www.icdevgroup.org/docs/xmldocs.html

 1-5. All as above, but with properly writing and formatting the
      text, as expected in DocBook/Interchange XML format.

 6. Port old documentation that is not yet ported to xmldocs

 7. Help processing unformatted input we'd hopefully receive

 8. Work on items from the TODO list (xmldocs/TODO file)

 9. Anything else you wish. Knowledge and initiative give you
    relevance and credit


[4]: XMLDOCS History

Davor Ocelic suggested documentation redesign in summer 2004, few months
after joining ICDEVGROUP. There have been multiple efforts to do that
already, but all failed for one reason or another.

The effort was blessed by ICDEVGROUP, and docelic was given practically
free hands to see if the idea would take us anywhere.

After we agreed on general guidelines and format, docelic programmed the
necessary infrastructure in Perl and DocBook XSL.

docelic's plan was to write Perl programs that would parse Interchange source 
code and extract information relevant for the documentation. This would
allow documentation to stay current (to a great degree!) while requireing
only small amounts of manual work. Those scripts form the base of xmldocs.

The DocBook XSL work was related to the choice of DocBook XML as our
native format. DocBook XML was suggested by our team leader, Stefan Hornburg.

docelic got the script and DocBook layer working, and started "porting" old
documentation along with writing new pieces, examples and everything else
that was missing, or existed but was out of date. At the same time, Perl
programs were improved as needed.

The "old documentation" was quite big, but still small compared to all the
advancements Interchange has seen in recent years. Most of it was written
by Mike Heins, Sonny Cook and Jon Jensen, and a few other people who are no
longer associated with Interchange. Of *currently* available text in xmldocs
documentation, the majority is based on that work.

Xmldocs is a joint effort of ICDEVGROUP, even though to date, docelic did
all of the work on the design and supporting infrastructure, and a lot
on the documentation itself as well.

We want to encourage contributions to xmldocs, to ensure the last missing
bit for its success and survival. So far, it happened that docelic was the
rare person having enough free time and enough interest in the
documentation to actually do some work, but this is of course not ideal or
feasible in the long run. (Even though the amount of work needed is getting
smaller every day - once the "backlog" is processed, staying current with
the codebase changes will be no trouble at all).

So, pick the tasks that match your skills and let's drive Interchange
documentation (and Interchange itself) somewhere better :-)

-Interchange Development Group, http://www.icdevgroup.org/


More information about the interchange-users mailing list