Thanks Francis, those are important considerations. Why GitHub below?. I assume that the ASF continues to offer GitHub access to project repositories and so this is an ideal structure to be alongside of if not embedded in. So these comments are in that context. (It is to be understood that such a repository would not be mirrored in the AOO project repository.)
1. Participants need to set their .gitattributes files to recognize *.odt, etc., as binary. I assume the master repository for the documentation work will already do this as part of loading the OpenOffice.org 3.2 documentation files. 2. The Open Document Format (ODF) does provide for plain XML forms of the common ODF types. The practice is to add "flat" to the name, so types *.fodt, *.fodc, etc., as well as *.xml. These document forms are accepted and produced by LibreOffice, perhaps other ODF-supporting products. I don't believe there are such provisions in AOO. These are text forms and so git change control, versioning, and patching (pushed changes) can work at the within-document level. 3. Because binary-file differences are not particularly meaningful, even if .git provided them, it seems that change-tracking, however limited it might be, is needed as part of pushed changes. So there needs to be some sort of governance for how this all works, along with ways for users to contribute. I would expect GitHub issues would be used, and there is also a pending GitHub discussions feature that would be useful. 4. With respect to governance, the way LibreOffice organized to operate a documentation team might be useful to review. Regardless of how one might feel about LibreOffice, the fact that there is a *successful* documentation effort at The Document Foundation should not be dismissed lightly. 5. Another interesting source of practices might be with respect to the OASIS OpenDocument Formats project. The ODF specifications are ODF documents and there was a move to handle editing and changes via a repository. I have not followed that, and I don't know that it is anything easy for ODF-project observers to learn from. The changes that I saw reduced the transparency of ODF TC document production. I don't know if that is still the case. ALTERNATIVE ARRANGEMENTS 6. Although the ODF specifications are developed using ODF formats, the specifications themselves are published in both PDF and HTML forms. The large *.odt files of the 4-part specification are also made available. It would not be necessary to publish ODF forms of the documentation beyond the documentation project and also accessible via observers. 7. Another option to consider has to do with how heavily Markdown is used on GitHub. There are a variety of transformers from Markdown to other forms (and other forms to Markdown). The complication with respect to Markdown has to do with images and other inclusions into a document file. (I.e, embedding Calc examples as well as screen captures and other images and graphics). That is an issue for the flat ODF formats as well. There needs to be some care about *which* Markdown, and being untethered from whatever GitHub does for Markdown over time. How intra-document, inter-document, and document-component links are handled is a factor. 8. It is useful to remember that GitHub provides Wikis as parts of projects as well as Issues and other provisions. You can also host a documentation web site in a project subfolder and use various techniques for authoring that particular documentation. There are ways to use node.js for that, generating blogs or pages, but one can also do it directly in a text editor. The Git source-code management and push discipline applies. End of brain dump 1.0 on this topic. - Dennis -----Original Message----- From: F Campos Costero <fjcc.apa...@gmail.com> Sent: Thursday, January 14, 2021 22:01 To: doc@openoffice.apache.org Subject: Re: Proposed Process for Documentation Keith - Have you looked into using Git with the odt file format. I did a quick search and it seems that Git can only handle a plain text version of the document if you want to see a Diff between two versions. So you could see which words had changed and differences in the grouping of text in paragraphs but things like the formatting of text or arrangement of images with respect to the text could not be tracked through git diff. Of course, changes could be tracked within the odt file, though even that is not comprehensive. For example, changing a paragraph's style does not seem to be captured. Dennis's point about how edits will be coordinated and versions controlled is very important.. I have no experience with technical writing beyond writing drafts and handing them to "the documentation people" to do their magic, so I can't give any really informed advice. The matter does bear some very careful thinking and discussion. Luckily, we will not have to deal with a huge team right away. regards, Francis On Thu, Jan 14, 2021 at 10:26 AM Keith N. McKenna <keith.mcke...@comcast.net> wrote: > On 1/13/2021 6:17 PM, Dennis Hamilton wrote: > > I don't see an attachment (apart from the digital signature). Is > > there > a GitHub reposi8tory set up available? > > > > Good news though. > > > > I am curious how the coordination of edits and the use of GitHub > > version > control will be navigated. I look forward to seeing how that unfolds. > > > > - Dennis > > > Sorry about that. I could claim it was a senior moment, but since you > have a few years on me that one is not going to work. This time I am > attaching it. > > Keith > > -----Original Message----- > > From: Keith N. McKenna <keith.mcke...@comcast.net> > > Sent: Wednesday, January 13, 2021 13:34 > > To: doc@openoffice.apache.org > > Subject: Proposed Process for Documentation > > > > Greetings All; > > After a discussion on legal@, as long as we do not include them in > > an "Official Release" we can use the .odt files for version 3 that > > are stored on the mwiki to bring them up to date for version 4.x.x and > > above. > > > > Attached is a proposed process utilizing a GitHub repository for > > version control of the User Guides and other Documentation. It is in > > .odt format with changes enabled. Please feel free to edit it and/or > > make any comments you feel are needed. > > > > Regards > > Keith > > > > > > -------------------------------------------------------------------- > > - To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org > > For additional commands, e-mail: doc-h...@openoffice.apache.org > > > > --------------------------------------------------------------------- To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org For additional commands, e-mail: doc-h...@openoffice.apache.org
