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
https://t.me/joinchat/ALeRuUFCxyZY0wzoddldWQ
Live TDF Jitsi Room
https://jitsi.documentfoundation.org/tdfdocteam
Completed items:
Pending items:
News:
Topics and Discussion:
Proposal for a change to the NextCloud workflow (DaveB)
See: https://nextcloud.documentfoundation.org/s/9FqwWK3m6Cy2zHQ
+ 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
Templates:
+ 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
version
+ 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.