I wonder if/how the LibreOffice documentation could take benefit from DITA. Has this been considered/discussed already?
Nino
Documentation Team Meeting, July 27th 2016, 20:00 UTC.
[...]
Nina wrote:
I wonder if/how the LibreOffice documentation could take benefit from
DITA. Has this been considered/discussed already?
What has been periodically discussed, is listing topics for which
articles of 500 - 5,000 words, as appropriate, are written. The idea
being that the articles could be massaged for the specific output media
format. In theory, this would mean documentation was consistent across
media formats, and, when the base article was updated, it would ripple
throughout the documentation universe.
In practice that hasn't has happened.
I'd hazard that the following are the primary reasons why that
hasn't/won't happen:
* Topic Completeness;
* Document reuse is, at best, non-trivial;
* This is not how ODF Authors has historically created documentation;
Topic Completeness
Going by the Design Survey for Draw, the following are the most common
uses for Draw:
* Creating diagrams;
* As an MS Visio replacement;
* Schemas;
* PDF Editing;
* Network diagrams;
* Flowcharts;
* UMLs;
* Drawings;
* Block Schemas;
* Block Diagrams;
* Algorithms;
* Vector image editing;
Will an article that describes how to do Block Schemas with Draw,
suffice for those that want to know how to do a Block Diagram?
Will a how-to for UMLs suffice for algorithms?
Equally problematic is appropriate indexing.
One can write a great article describing how to create and use Radar
Charts with Calc, but will it occur to anybody to also index the article
under Star Plots, Spider Charts, Polar Charts, or any of the dozen other
names used for that type of chart?
Document Reuse is Non-trivial
Every type of media has its own set of editing and layout requirements.
* The purpose of the material affects how it is formatted. By way of
example, a psychology research article will be formatted according to
_The APA Publication Manual_ guidelines, whilst a research article on
the Bible will be formatted according to _The SBL Handbook of Style_;
* The target audience affects both vocabulary and syntax. Look at the
textual differences between the British and the American edition of any
book that was first published in England;
*The output format affects how material is put together. Consider the
differences between a script for a theatrical play, a script for a film,
a script for a radio play, and a script for a TV production;
ODF Authors document creation history
What is useful, is examining why things are currently done the way that
they are. A switch to "topic orientated articles" as a focal point
requires a major shift in the creative psyche of ODFAuthors.
As far as switching to DITA goes, the first step would be for
LibreOffice to be able to import/export to that markup language. Until
that happens, adopting DITA is a non-starter, with topic focused
articles as being the closest possible adoption.
jonathon