Minutes of Documentation Team Meeting, July 27th 2016, 20:00 UTC.

classic Classic list List threaded Threaded
3 messages Options
Olivier Hallot-4 Olivier Hallot-4
Reply | Threaded
Open this post in threaded view
|

Minutes of Documentation Team Meeting, July 27th 2016, 20:00 UTC.

Documentation Team Meeting, July 27th 2016, 20:00 UTC.

Hangout link:
https://hangouts.google.com/call/cpmf5ftoubdktbw7rataljc6due

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
           +less pages
      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
                  + Certificate?
                  + 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
                    implemented
              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.


+ How can we improve our documents visibility?

    http://www.libreoffice.org/get-help/documentation/

    + Are our books a true LibreOffice companion product?
    + improve downloads of our books?
    + connect LO users to our docs and books?
        Olivier: Have links from the help menu to our documentation
        https://bugs.documentfoundation.org/show_bug.cgi?id=96015
    LibreOffice Help menu:

    LibreOffice Help
    What is this?
    ---
    Online Help ( https://help.libreoffice.org/Main_Page )
    Download Offline Help ( likely only enabled if offline help isnt
installed, but wont be useful for locales that dont have localized help.
e.g. arabic )
    User Guides ( http://www.libreoffice.org/get-help/documentation/ )
    ---
    Questions & Answers ( askbot.libreoffice.org )
    Submit Feedback ( BSA or bugzilla or
http://www.libreoffice.org/get-help/feedback/ )
    Community Support (
http://www.libreoffice.org/get-help/community-support/ )
    Professional Support (
http://www.libreoffice.org/get-help/professional-support/ )
    ---
    Check for updates
    License information
    Donate to LibreOffice
    ---
    About LibreOffice


    + get more book translators,
    + L10N contributions to documentation

+ Documentation meetings in Brno.
    + Set a meeting room for the documentation team
       + update brainstorming on documentation issues
       + Set targets for documentation in next 6 mo or 1 year.
       + Other topics





--
Olivier Hallot
Comunidade LibreOffice
Rio de Janeiro - Brazil - Local time: UTC-03
http://ask.libreoffice.org/pt-br

--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
Nino Nino
Reply | Threaded
Open this post in threaded view
|

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?

Nino

On 28.07.2016 01:59, Olivier Hallot wrote:
> Documentation Team Meeting, July 27th 2016, 20:00 UTC.

[...]



--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
jonathon-6 jonathon-6
Reply | Threaded
Open this post in threaded view
|

Re: Minutes of 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




--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted