Documentation Team Meeting Minutes September 10th 2020

Documentation Team Meeting Minutes September 10th 2020 at 18:00 UTC.

Presents: Emiliano Vavassori, Samantha, Dave Barton, Felipe Viggiano,
Travis Stewart, Olivier Hallot

Many thanks to Emiliano for the minutes !

Telegram Channel

Live TDF Jitsi Room

Completed items:

Pending items:


Topics and Discussion:

Proposal for a change to the NextCloud workflow (DaveB)

    + Not a big thing, but tidies up the work done
    + Olivier: maybe better to watch it over for some days, then come
back inside ML with an approval
    + Emiliano: pt.5 - only Public and Archive subdirectories when
Guides are reviewed:
    + Maybe maintain the Feedback folder anyway, even if it is empty
    + Dave: someone prefer to link guides from the "Public" folder
instead of a copyinside the wiki
    + Olivier: using the Extensions site (now the old one) to link guides

DaveB: Impress Guide, Getting Started guide
    + Olivier: asks DaveB to take the role of Coordinator for the Get
Started Guide

    + Olivier: reviewed the template, checked and approved
    + Good and working template
    + Minor but visible changes
    + DaveB: Peter had some issues
    + If we can sort it out quickly, we should release a final/official
    + Olivier: checking a version from Jean which is really fine
    + Olivier: see that the color headings has been changed to black
    + DaveB: Do not muchlike the black headings, but can live with it.
    + Olivier: in the end I am fine

+ Olivier: Document from Regina on Lists & paragraph
    + Valuable document
    + really important document
    + Unfortunately the relationships between lists and holding
paragraph is quite complex

+ Travis Stewart: who is maintaining XML help pages
    + quite hard and confusing
    + Olivier: it is me
    + Piece of XML from 2005, coming directly from Sun Microsystems needs
    + DaveB: legacy code
    + Plan to move away from XML (restructured text, markdown)?
    + Olivier: it has always been on the radar
      + It has to be readed offline (and also online)
      + It has to be translatable (weblate compatible)
      + Need systems to migrate older format to the new one
    + Evaluated many iteration of new technologies, good solution
      + they are better when starting from scratch
    + Part of the information inside help is the same of the guides
    + Is there a way to have only one source of information?
       + Not easy
       + Travis: single source is a buzzword
       + Not checked inside, no proposals

    + DaveB: why can't we use ODF as a format for help
    + Olivier: already though hardly about that
    + glitches that can be corrected with styles
      + how to point to correct places?
      + You can export a chapter, but reading from start to end is only
for a book and not so much online (search, indexing, bookmarks needed).
    + DaveB: can be done, but probably complicated
      + Olivier: agreed
      + watched into alphabetic indexes
      + discovered that they don't have hyperlinks
      + Olivier: documentation is key, without doc the software is dead
      + Checking inside the code myself to document functions
      + Put bugs on Bugzilla for the help, about 250+ bugs open
      + Mostly for changing wording, changed functions/functionalities
      + DaveB: for someone it is too much short and incomplete
      + Documentation strive to do the completeness
      + Olivier: online help has always had two goals:
        + Reference
        + Guide
        + If I can leverage docteam guides it would be more than fine
and focus on the reference
     + DaveB: can the guides be linked from the offline help?
     + Olivier: can do, but I need a stable layout of the information
inside guides
     + FLOSS contributors don't write specifications
     + lots of code and no specifications, so Olivier is digging the code
        + Asked that GSoC students will not get grades if they don't
write some specifications/documentation of their features
        + Travis: extreme development practices demands for the
developer to write documentation to let the CI/CD workflow
            + maybe not feasible

Meeting ajourned

Next meeting : *THURSDAY* September 24th 2020 at 18:00 UTC.