T[io]m, I don't think the documentation issue is as clear cut as Tim suggests. Here are my observations:-
1. The existing PDF documentation is excellent - far better than many commercial projects. This is partly due to the use of Framemaker, but mostly due to Tom's commitment, knowledge and skills. 2. In the ideal world, openEHR would have infrastructure that could readily allow for distributed documentation authoring in multiple languages with solid version management, from which PDF, XML and HTML outputs could be autogenerated, and which clearly differentiated Release vs. Draft status of both the specifications to which the documentation referred as well as the documentation versions themselves. Indexing of the documentation artefacts would be comprehensive and capable of being integrated with the HTML documentation bundle(s). 3. There is no affordable suite of products that can easily lead to such an ideal world. Any real-world solution will involve trade-offs. 4. Framemaker can, and does produce the best quality documentation in PDF format. 5. Framemaker is expensive and recent versions only run on Windows. 6. The openEHR community is still small such that few people will have the time, skills and willingness to contribute to authoring documentation. 7. Both Latex and DITA offer potential for single sourcing of documentation in PDF, XML and HTML. Both are supported by a range of cross-platform tools starting at zero cost. From a PDF quality perspective, neither matches Framemaker, particularly in the areas of UML and other diagram integration, version management through change bars or indexing. 8. DITA offers the best potential for distributed authoring, semi- automatic language translation, automated documentation builds. There is a rapidly growing array of tools supporting DITA editing and transformations. 10. DITA transformations to PDF, XML or HTML are normally done using the freely available, java-based DITA Open Toolkit. This DITA-OT is bundled with a number of XML editors, including oXygen. I've run DITA transformations in oXygen on Linux, Mac Os X, and Windows XP - from the same DITA source files on the same networked folder!! The behaviour and output is identical!! One rarely comes across such platform independence. However, tracking down errors within the DITA- OT can be time-consuming and frustrating. 11. DITA-based authoring using these modified XML editors has a long way to go to be usable by non-XML speaking authors - a parallel with the LaTex world, by the way. Framemaker 9 and Framemaker >7.1 supplemented with Leximation's DITA plugin are both potential options as a high quality authoring environment based on DITA. I've dabbled with both, and have my doubts - particularly if there's a desire to broaden the authoring base. 9. The existing Framemaker files could be converted to DITA using the low cost (Windows) tool MIF2Go. This (plus oXygen) could provide a relatively quick and painless path for Tim and others to produce XML/ HTML renditions of the current specifications for incorporation into applications. 12. My recommendation would be to consider migrating to DITA, with the proviso that:- Producing and maintaining documentation is a time consuming ( and often thankless) task. Producing and maintaining documentation of the current quality of the openEHR material will likely be an ongoing challenge to the openEHR community for years to come. eric ----- On 25/09/2009, at 7:18 AM, Thomas Beale wrote: > Hi Tim, > > I have said often in the past I would be happy to see the documents > move to such a format if: > a) anything remotely approaching the quality of FrameMaker can be > found (I have yet to see it; OpenOffice is not even close) > b) some is going to fund the changeover > > Others in this community may not care about visual quality - I am > interested in feedback on this point. > > I personally have no problem with PDF - it is an output format, not > an editing format, and most tools output PDF (including OpenOffice). > Personally, for readability, I think it leaves wikis and web sites > for dead, but of course the latter have a different function. > > I did have a plan for which I don't currently have enough time, > which is to get FrameMaker 9 (I have done that part of the plan) and > convert all the docs to structured DITA XML (which FM9 supports, > along with a lot of other tools I have never tried - > http://www.ditanews.com/tools/desktop_editors/ > ) from which they could potentially be converted to some other XML > for another tool. I don't have my head around all the publishing XML > formats yet, but I suspect it is possible. On the topic of help > files, it has already been done with FM9 XML output, and integrated > experimentally into a Java environment, so one thing Frame doesn't > do is lock you into anything (unless you think DITA XML is a lock-in). > > I don't know whether Latex is the right solution or not; I don't > know whether the GUI editors (main one seems to be Lyx) are any good > or not; editing raw markup is out of the question. > > I would be interested to know what the community thinks we should be > aiming for in terms of output and quality; the question of how to > get there can then be thought about separately. > > - thomas beale > > Tim Cook wrote: >> Hi All, >> >> Over the past several years I have discussed this issue with Tom >> Beale; >> on mailing lists, off mailing lists and in person. >> >> The issue is that Framemaker is a proprietary and basically non >> standard >> document format. I fully understand that Tom enjoys the desktop >> publishing capabilities that it gives him and that he is familiar >> with >> the application. >> >> However, we the "open content" community end up with a proprietary >> format (Framemaker) and a dead-end format (PDF) for specifications >> that >> are advertised as being open and available. >> >> It is almost the the ultimate sarcastic humor (on the scale of Monty >> Python) that here we are trying to deliver computable healthcare >> information and our own specifications are locked up in these two >> formats. We cannot manipulate them into any kind of help files in >> order >> to integrate them into an application and god forbid we think about >> machine translation into other languages. >> >> So, I have to ask myself, as well as all of the members of the >> openEHR >> community. What is wrong with the international, open standard for >> document layout; (La)Tex? It seems to work well for all major >> publishers, why can't it work for openEHR? >> >> Why do we not insist on our documentation being in a format that is >> more >> useful to us as a broad and open community? >> >> Thanks for listening. >> >> --Tim >> >> >> >> >> >> >> >> >> >> >> _______________________________________________ >> openEHR-clinical mailing list >> >> openEHR-clinical at openehr.org >> http://lists.chime.ucl.ac.uk/mailman/listinfo/openehr-clinical > > > -- > <OceanC_small.png> Thomas Beale > Chief Technology Officer, Ocean Informatics > > Chair Architectural Review Board, openEHR Foundation > Honorary Research Fellow, University College London > Chartered IT Professional Fellow, BCS, British Computer Society > > _______________________________________________ > openEHR-technical mailing list > openEHR-technical at openehr.org > http://lists.chime.ucl.ac.uk/mailman/listinfo/openehr-technical
