Mail Archive Home | architecture List | Febuary 2005 Index
| <-- Date Index --> | <-- Thread Index --> |
Hi David,I think you made a very good summary of the issues. I have to admit that I never thought of the required document structure for internationalization purposes. Do you think XML documents should contain multiple elements for internationalized content (using the xml:lang attribute), or would you go for separate documents, using some clever XML diffs to retrieve updated elements?
Another approach I'd like to see in open source documentation is the increased use of wikis. By splitting a large user guide into small wiki pages, we could allow users to comment or even change the on-line documentation, fixing mistakes and clarifying it. By gathering the wiki contents from time to time into an integrated version, we could then provide an up-to-date and improved documentation. Obviously, using an open, XML format to model the document would just make the integration easier.
Coming back to Forrest, nothing prevents you to write long documents with it: our XQuark user guides, which are thirty or forty pages long, are done with it. The limitations are more related to the document structure capabilities: they are clearly not as rich as in docbook, but most of the basic functionalities are supported: sections, paragraphs, lists, images, tables, hyperlinks, etc.
By using OOo in conjunction with the Forrest DTD, thanks to the round-trip XSL-T transforms and OOo template we developed, we have a WISIWIG documentation editor that uses semantic XML as its storage format. Forrest provides us with automated publication facilities from the semantic XML, both in HTML and PDF.
Cheers Antoine David Li a écrit :
I agree that it's too early to call for adapting a standard on ObjectWeb's documentation. Moreover, it's probably not the responsibility ObjectWeb to even call for a standard on project documentations as it's not the objective of the consortium.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.