Mail Archive Home | architecture List | Febuary 2005 Index
| <-- Date Index --> | <-- Thread Index --> |
The requirement for document standards comes from practical cooperation between projects. The discussion started from my experience with Chinese project that translated ObjectWeb document into Chinese. There is also a Japanese project underway. One practical problem we are facing is the difficulty of maintaining the translated documents up-to-date with the latest official document. Why? The formats such as Word or HTML are difficult to properly create delta (diff) so most likely the translators have to manually inspect the entire documents for change. Well, that gets to be very boring and tedious. As the projects are done on volunteers base, it's hard for us to keep translator interested in updating. Also, for the translators, they have no problem reading the documents in the original language and their primary interests are technical. And now, we are left with a site of outdated translated documents. :( It would be good for the projects to adapt an document format that would help the above mentioned cooperation easy.
We are not really "deciding" on a format standard; it would at best be a recommendation and it's up for project team to make their own decision whether to use it or not. There is no mean of enforcing a standard in the organization.
The basic list of requirements layout from the first post on document format is:
1. open format 2. easy to generate diff 3. support for translation maintenanceAlso, I agree that it's also important to consider easiness of maintenance of the documents and tool support.
However, I don't think we can talk our way to a solution. It's already hard enough to pay engineers to write documents; it's even much harder to have them do it for free. This will have to depend on individual project to decide the best way to approach this. At most, we can archive rough consensus and build the cooperation on top of that.
Gathering from the discussion, I guess semantic based XML format is a rough consensus. Enhydra is using DocBook and XQuark is using Apache Forrest. I guess as long as we are on XML based format, it's always possible to write a XSL to transform between them. DocBook is good for long document and Forrest seems to be easier for shorter one.
As for tools, there are fancy commercial products that will do a very good job. However, it's probably not a good way to go. OpenOffice is being used by both Enhydra and XQuark teams.
DocBook http://www.docbook.org Apache Forrest http://forrest.apache.org/Appreciate both Enhydra and XQuark teams to share their experience and I think sharing is what the open source is all about. We can't force a standard upon each other; only through sharing and cooperation we could move forward.
On Feb 15, 2005, at 4:21 AM, claus.hirth@xxxxxxxxxxxxxx wrote:
(1) In my opinion it is far too early to decide on whether DocBook or OpenOffice etc would make the most practical standard format for ObjectWeb documentation. Why is it too early? Because we did not put down any requirements a documentation format must meet. If we have no accepted list of requirements we can't use clean-cut arguments like * "Format F is no good because it does not address requirement R". * "S1 covers all critical requirements". (2) Aside from the documentation standard format itself we must take into consideration the processes involved to maintain documentation. We must do a lot better on redactional process support than most newspapers do today. To focus on the first edition only, and not giving careful thought to all the use cases that affect documentation and which documentation is part of will make us end up with a standard that will not serve our needs. Claus Hirth Diplom-Informatiker Universität
| <-- Date Index --> | <-- Thread Index --> |
Powered by MHonArc.
Copyright © 1999-2005, ObjectWeb Consortium | contact | webmaster.