Doc Team Meeting Minutes

Wednesday November 14th2018, at 19:30 Berlin Time

Presents: Drew, Cathy, Heiko, Olivier

Fall back chat:
https://irc.documentfoundation.org/?settings=#libreoffice-doc

TDF Jitsi room
https://jitsi.documentfoundation.org/tdfdocteam

Completed Action Items:

Hi,

please, could you further explain:
  + Supporting minor updates to published guides (pdf file)

What is the agreed notification workflow with every guide update for all
l10n teams translating these guides (content-wise, i.e. notifying "this
sentence in this chapter/page was changed from this to this" etc.) so that
the translation process continues with the really-latest version (after an
official version is already published) and as hassle/confusion-free for
l10n teams as possible?

With the delicate translation process going on in parallel with the
considered minor content updates I would instead suggest to create odt/pdf
with errata or corrigenda of a guide (and all its chapters) that gets
updated regulary and is finally merged with the guide only with its next
iteration of publication.

To quote wikipedia/*Chicago Manual of Style
<https://en.wikipedia.org/wiki/Chicago_Manual_of_Style>*, "Errata, lists of
errors and their corrections, may take the form of loose, inserted sheets
or bound-in pages. An errata sheet is definitely not a usual part of a
book. It should never be supplied to correct simple typographical errors
<https://en.wikipedia.org/wiki/Typographical_error> (which may be rectified
in a later printing) or to insert additions to, or revisions of, the
printed text (which should wait for the next edition of the book). It is a
device to be used only in extreme cases where errors severe enough to cause
misunderstanding are detected too late to correct in the normal way but
before the finished book is distributed. Then the errors may be listed with
their locations and their corrections on a sheet that is tipped in
<https://en.wikipedia.org/wiki/Tipped-in_page>, either before or after the
book is bound, or laid in loose, usually inside the front cover of the
book. (Tipping and inserting must be done by hand, thus adding considerably
to the cost of the book.)"[2]
<https://en.wikipedia.org/wiki/Erratum#cite_note-2>

Thanks,
Martin

V V sre., 14. nov. 2018 ob 20:31 je oseba Olivier Hallot <
olivier.hallot@libreoffice.org> napisala:

Hi Martin,

Thanks for joining in the conversation.

Hi,

please, could you further explain:
  + Supporting minor updates to published guides (pdf file)

In fact further examination of what this would encompass the purpose behind
adding it to the call agenda.

The second or third week I joined in on the calls it happened that Olivier
and myself were the only two on board that day. Olivier shared some
thoughts, at length, on treating the Guide publication process more closely
to how a software package is released. With an important goal, among a few
others, of bringing Guide publishing dates closer releases of the software.
The idea has been bounced around between others on a few subsequent calls.

What I've taken away from these discussion would be to have a work flow
which supports major and a minor publication of a Guide.

A major publication of a Guide would involve updates to every document
(master document and all chapter/appendix documents) along with other
components such, cover art for one example.
It could add or remove chapters or make other changes in chapter structure.
It includes the production of two set of documents, one including an ODF
master document, ODF text documents for each chapter or appendix and the
other set pdf files created from the first set.
The publication process includes then the production of an official print
master, including ISBN registration as a final update, which is then sent
to a print service.
This represents the current publication process.

Publishing a minor version of a Guide could, but may not, require a change
to the master document beyond generating new TOC/Alpha Index tables, it
would include updates of some subset of chapter or appendix documents.
A minor publication process produces both sets of files, ODF and PDF.
No print master is produced for the minor publication, therefore no
registration of a new ISBN is needed.
***I have some open questions regarding the last point about the ISBN and
if there might be some legal requirement of a clearly distinct name from
the registered printed book, even if true it is just something to account
for in the workflow.
These minor publishing events would happen between the full, major, Guide
releases.

This change would require us to change the file names to include a document
release number in addition to the software release number, only those files
which actually change would increment the document release number so that
at a macro level you could easily see which of the constituent files
actually changed based on the file names in the release.

What is the agreed notification workflow with every guide update for all
l10n teams translating these guides (content-wise, i.e. notifying "this
sentence in this chapter/page was changed from this to this" etc.) so that
the translation process continues with the really-latest version (after an
official version is already published) and as hassle/confusion-free for
l10n teams as possible?

There would always be, at a minimum, the ability to generate a delta
between the present and most previous copy of an individual file to see
what exactly changed with the compare documents function using ODF files.

With the delicate translation process going on in parallel with the
considered minor content updates I would instead suggest to create odt/pdf
with errata or corrigenda of a guide (and all its chapters) that gets
updated regulary and is finally merged with the guide only with its next
iteration of publication.

If publishing were always going to dead trees for a medium I'd say
absolutely the better way to go.

That is need not be the case here however and I would put forward some
opinions:

No document of this type publishes without deficiencies either by error or
omission.

It is valuable to make the most accurate information available to users as
quickly as reasonably possible.

The quicker the team can get feedback from users seeing the changes made to
address these deficiencies an the more readers overall increases the teams
ability to make higher quality documents.

I think publishing complete documents, with changes incorporated, will
generate both better and more feedback than a list of changes in a separate
addendum document.

As I said above this is really the first time I've put what I've taken from
our batting the idea around on a few calls into text and thanks again for
the nudge here.

That then is just a gross view of the thinking and certainly needs more
fleshing out.

Given that it's 1AM here though it is a good spot to end this email.

I'm looking forward to continuing the conversation with you and others here
on the morrow.

Looking forward to hearing your thoughts.

Best wishes,

Drew

Howdy list,

So, took what was in my last email on this idea of Major and Minor
publishing of Guides and put a bit more structure to it as Proposal in the
Doc Team work-group folder.

@Martin I wasn't sure if you were already had edit rights in the work-group
folder, saw you had an account on the server though, so sent you a direct
share link via NC with edit rights to the file.

Also created a public read only link for this 'work in progress',
https://nextcloud.documentfoundation.org/s/Ks7n7XroE55tKTg

There is also a text file, 'Document Proposal' in the same folder covering
details of the general work flow for publishing a Guide, the file I added
today is not intended to replace the contents of the earlier, rather to
compliment it, and would, I think, not effect a great deal of what is in
that workflow, with a notable exception of the file naming scheme.

I've added a requirement into the current versioning proposal regarding
support for the I10n teams given the email exchange here.

Feel free to comment in the document, or make changes even, if you have
write access there, or to give feedback on the ML here, which is also the
case for those reading it via the read only link above.

Thanks,

Drew