Present: Olivier, Jean , Leo, Marco Pinto, Chrystina
+ How to turn the documentation job fun and thrilling?
Jean: I've never found a good answer.
+ no need to do the whole chapter
+ need to indicate up to where it was updated
+ people don't notice the things to add.
+ Most people that want to help don't know the software
+Know more than the average
Leo: Chapters too big to work with
Jean: May be we have to translate from other lang to English
+ get more authors?
+ Author's peer/community recognition
Leo: Contributor of the month
+ like in Pootle
+ Interview with Authors
Olivier: Page with all photos of the authors
+ List of Authors
Leo: Hall of fame
+ Medals, once the doc is published.
+ Combine with marketing
+ spread the word,
+ people behind the books, like devs
+ Narrow gap between book release date and software release date
Leo: On Getting Started (GS) what to be changed?
Someone to flag what to change and add
Jean: who is going to do it?
Olivier: not every new feature will do to GS.
Leo: On next version (6) rethink on what to write
about, rework the text
+ start the new version right after the feature is
Jean: People want to see the sw before writing about.
+ Lowering author's entry barriers
Leo: workload: split the chapters
or split the tasks: text, screen capture, revisions.
Re: Minutes of Documentation Team Meeting, July 27th 2016, 20:00 UTC.
>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
* Topic Completeness;
* Document reuse is, at best, non-trivial;
* This is not how ODF Authors has historically created documentation;
Going by the Design Survey for Draw, the following are the most common
uses for Draw:
* Creating diagrams;
* As an MS Visio replacement;
* PDF Editing;
* Network diagrams;
* Block Schemas;
* Block Diagrams;
* 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.