You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doc@openoffice.apache.org by "Keith N. McKenna" <ke...@comcast.net> on 2021/01/13 21:33:31 UTC
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
RE: Proposed Process for Documentation
Posted by Dennis Hamilton <or...@msn.com>.
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 <fj...@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 <ke...@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 <ke...@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-unsubscribe@openoffice.apache.org
> > For additional commands, e-mail: doc-help@openoffice.apache.org
> >
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Proposed Process for Documentation
Posted by Jean Weber <je...@gmail.com>.
Just to clarify: I have zero interest in being involved in any official or
group documentation effort. The only reason I mention the ODFAuthors
licensing is because that’s what existing 3.x docs (and my own books) are
under. Any reuse/revision/updates cannot be under A2. Otherwise, my
preferences are irrelevant.
Jean
On Fri, 22 Jan 2021 at 10:50 Dennis Hamilton <or...@msn.com> wrote:
> 4. Jean Weber tends to prefer the ODFAuthors CC-BY and GPL dual
> licensing, although maybe that is mainly about her "Getting Started" book
> on AOO. That has to be nailed down at the beginning, because contributors
> need to know what licensing they are contributing under.
>
> - Dennis
>
>
Re: Proposed Process for Documentation (2)
Posted by Jean Weber <je...@gmail.com>.
The current LibreOffice docs-production organisation is only slightly
changed from the way OOoAuthors did things at OpenOffice. (OOoAuthors
rebranded as ODFAuthors in an attempt to include both OOo and LO - and any
other spin-offs, in case they occurred. It later transformed into the
official LO Docs team when AOO wasn’t interested.)
I can tell you a great deal about the origins of OOoAuthors and its
evolution as a producer of OOo docs, but I think our success was partly due
to a very minimal process and a willingness of the small group to forge
ahead with production even when the write-review-edit sequence stalled due
to lack of enough people to do everything as intended.
LO has managed to recruit more people, but otherwise the process is much
the same, just followed a bit more in practice.
Jean
On Fri, 22 Jan 2021 at 10:50 Dennis Hamilton <or...@msn.com> wrote:
>
> NOTE: You don't have to do this all at once, but there needs to be enough
> foresight in an initial organization being able to evolve. It would be
> useful to know what was sufficient for ODFAuthors to get work done. I
> Also think it is sensible to see how LibreOffice organized for successful
> production of user documentation. And check on the AOO Community Forum for
> interest and ideas.
>
RE: Proposed Process for Documentation
Posted by Dennis Hamilton <or...@msn.com>.
Keith,
My impression is that everyone was waiting for you. I assume you have bounced your ideas off the PMC.
If you set up an off-ASF public GitHub project, there are a number of things you need to deal with. (I am assuming you can't do it on-ASF because it violates the rule about non-Apache licensing in a public ASF repository.)
NOTE: You don't have to do this all at once, but there needs to be enough foresight in an initial organization being able to evolve. It would be useful to know what was sufficient for ODFAuthors to get work done. I Also think it is sensible to see how LibreOffice organized for successful production of user documentation. And check on the AOO Community Forum for interest and ideas.
1. There needs to be some degree of a governance structure. Nothing majestic, but enough for ground rules about usage and contribution to be understood. And there is the usual matter of granting commit rights and also how to handle push requests or other ways for folks to submit changes/contributions, etc. Because there is no merging with respect to binary content, collisions need a mechanism for resolution also. There might be designated editors.
2. There needs to be some organization for production. Probably with release tags and also migration to drafts, derivation of candidate versions of documents, and the creating of final flavors (the editable, any non-editable form such as PDF). Also, anywhere that web versions will be posted and how versioning works there.
3. An archive of the core base documents would be handy also. There might also be style guides, style sheets (template documents?), etc. That sort of thing might be grown into.
4. Jean Weber tends to prefer the ODFAuthors CC-BY and GPL dual licensing, although maybe that is mainly about her "Getting Started" book on AOO. That has to be nailed down at the beginning, because contributors need to know what licensing they are contributing under.
I am interested in seeing this sort of thing work. I'm not an AOO committer and not interested in AOO dev these days. Given that, I can help at the outset. I still have an interest in documentation [;<).
- Dennis
-----Original Message-----
From: Keith N. McKenna <ke...@comcast.net>
Sent: Thursday, January 21, 2021 13:25
To: doc@openoffice.apache.org
Subject: Re: Proposed Process for Documentation
On 1/15/2021 1:01 AM, F Campos Costero wrote:
> 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
[orcmid] [ ... ]
>
> regards,
> Francis
>
Yes I did. In fact all the revisions of the proposal were done using my GitHub account and it worked quite well. It will offer to open the binary file in the external application. You are correct that it does not handle a diff, but that is not why I was suggesting using it. It was simply as this is the version control system that the project has chosen to use and trying to implement anything different would require yet another VM for the project and the incumbent overhead of finding volunteers with the necessary skills to maintain it.
As I am seeing no other comments from the documentation team I am planning on writing this attempt off as one more failure on my part.
I will continue on my own to attempt to get a usable 4.1.x and 4.2.x Getting Started guide completed. Any help in getting these done will be greatly appreciated.
Regards
Keith
> On Thu, Jan 14, 2021 at 10:26 AM Keith N. McKenna
> <ke...@comcast.net>
> wrote:
>
>> On 1/13/2021 6:17 PM, Dennis Hamilton wrote:
Re: Proposed Process for Documentation
Posted by marcia wilbur <ai...@well.com>.
Thanks for clearing that up. My mistake then, 400 pages for get started.
Still an important resource for some people, I'm sure.
There are a lot of details included in the get started guides.
However, as previously discussed with Olivier and the doc team at Libre last year, the mix of OS screen captures and options causes confusion and even at 400 pages or so - is incomplete.
----- Original Message -----
From: "Jean Weber" <je...@gmail.com>
To: doc@openoffice.apache.org
Sent: Sunday, January 24, 2021 2:17:13 AM
Subject: Re: Proposed Process for Documentation
On Sun, Jan 24, 2021 at 4:32 PM marcia wilbur <ai...@well.com> wrote:
>
> Additionally, I have not reviewed the entirety of this self published guide -
> and great if Jean wants to work on that - however, when I was volunteering
> with Libre, I noted the GSG was 700 pages or so. If the scope of that guide
> is this complete, that is a resource.
If you're referring to the LibreOffice Getting Started Guide, it is a
bit over 400 pages - nowhere near 700.
My book on AOO is about 300 pages, as it covers fewer topics.
Jean
> On Sat, Jan 23, 2021 at 7:04 PM Dennis Hamilton <or...@msn.com> wrote:
> >
> > Jean Weber has offered to update her self-published "Getting
> > Started" book on AOO to be suitable for AOO 4.1 users (unless 4.2 is
> > imminent, I suppose). It would seem valuable to rely on that, including
> > assisting her, rather than have duplicate effort inside the AOO project.
> > So maybe there should be a different focus for the AOO effort, starting
> > with OO 3.2 User Guides.
> >
> > - Dennis
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Proposed Process for Documentation
Posted by Jean Weber <je...@gmail.com>.
On Sun, Jan 24, 2021 at 4:32 PM marcia wilbur <ai...@well.com> wrote:
>
> Additionally, I have not reviewed the entirety of this self published guide -
> and great if Jean wants to work on that - however, when I was volunteering
> with Libre, I noted the GSG was 700 pages or so. If the scope of that guide
> is this complete, that is a resource.
If you're referring to the LibreOffice Getting Started Guide, it is a
bit over 400 pages - nowhere near 700.
My book on AOO is about 300 pages, as it covers fewer topics.
Jean
> On Sat, Jan 23, 2021 at 7:04 PM Dennis Hamilton <or...@msn.com> wrote:
> >
> > Jean Weber has offered to update her self-published "Getting
> > Started" book on AOO to be suitable for AOO 4.1 users (unless 4.2 is
> > imminent, I suppose). It would seem valuable to rely on that, including
> > assisting her, rather than have duplicate effort inside the AOO project.
> > So maybe there should be a different focus for the AOO effort, starting
> > with OO 3.2 User Guides.
> >
> > - Dennis
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Proposed Process for Documentation
Posted by marcia wilbur <ai...@well.com>.
Hi.
Recently, in one post, I note someone mentioned the prospect of different guides for different OS. This is important because having a guide with various screen captures and instructions for mac doesn't necessarily work with GNU Linux features.
The past documentation was a mix of Windows/Mac and GNU Linux captures and not always relevant.
Additionally, I have not reviewed the entirety of this self published guide - and great if Jean wants to work on that - however, when I was volunteering with Libre, I noted the GSG was 700 pages or so. If the scope of that guide is this complete, that is a resource.
The effort here for GNU Linux I am putting in - is to create clear and concise - current info relevant to GNU Linux users.
As a technical writer of GNU Linux documentation for over 20 years, I believe the guides I am creating will be useful.
In fact, I created an installation guide and was contacted by a user who informed me this would have been useful years ago when he tried to install.
I just hope my effort here will be useful to the audience.
----- Original Message -----
From: "F Campos Costero" <fj...@gmail.com>
To: doc@openoffice.apache.org
Cc: "Keith N. McKenna" <ke...@comcast.net>
Sent: Saturday, January 23, 2021 8:06:05 PM
Subject: Re: Proposed Process for Documentation
I agree that there is no significant conflict here. The only outstanding
question is where to host the documents. Settling that should not inhibit
anyone from working on documents.
One feature of the Apache governance method is that volunteers decide what
will get done and how it will be done. The question of document hosting can
be decided by the interested parties. The PMC should know what will be
done, in case it is obviously unacceptable, but making a decision and
taking action is largely up to the few people in this discussion.
I will find Jean's message about her Getting Started Guide and ask for more
details about what she is considering.
Francis
On Sat, Jan 23, 2021 at 7:04 PM Dennis Hamilton <or...@msn.com> wrote:
> -----Original Message-----
> From: Keith N. McKenna <ke...@comcast.net>
> Sent: Saturday, January 23, 2021 15:43
> To: doc@openoffice.apache.org
> Subject: Re: Proposed Process for Documentation
>
> [orcmid] [ ... ]
>
> As there are obviously still conflicting views on how documentation should
> be handled. I have decided to step away from this entirely and concentrate
> my volunteer efforts elsewhere.
>
> Regards
> Keith
>
> [orcmid]
> I don't think there are conflicting views. There have been considerations
> of a few approaches and ways of satisfying ASF sensibilities. There are
> some concerns about ASF sensibilities with regard to carrying
> "foreign"-licensed materials in ASF repositories.
>
> For example, one option would be going the AOOAuthors route and hosting
> that effort on GitHub.
>
> The alternative Keith favors involves hosting within the AOO project in a
> manner that does not conflict with ASF sensibilities about licenses. As
> far as I can tell, no one is stopping that being set up and contributors
> recruited.
>
> One caveat. Jean Weber has offered to update her self-published "Getting
> Started" book on AOO to be suitable for AOO 4.1 users (unless 4.2 is
> imminent, I suppose). It would seem valuable to rely on that, including
> assisting her, rather than have duplicate effort inside the AOO project.
> So maybe there should be a different focus for the AOO effort, starting
> with OO 3.2 User Guides.
>
> - Dennis
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Proposed Process for Documentation
Posted by F Campos Costero <fj...@gmail.com>.
I agree that there is no significant conflict here. The only outstanding
question is where to host the documents. Settling that should not inhibit
anyone from working on documents.
One feature of the Apache governance method is that volunteers decide what
will get done and how it will be done. The question of document hosting can
be decided by the interested parties. The PMC should know what will be
done, in case it is obviously unacceptable, but making a decision and
taking action is largely up to the few people in this discussion.
I will find Jean's message about her Getting Started Guide and ask for more
details about what she is considering.
Francis
On Sat, Jan 23, 2021 at 7:04 PM Dennis Hamilton <or...@msn.com> wrote:
> -----Original Message-----
> From: Keith N. McKenna <ke...@comcast.net>
> Sent: Saturday, January 23, 2021 15:43
> To: doc@openoffice.apache.org
> Subject: Re: Proposed Process for Documentation
>
> [orcmid] [ ... ]
>
> As there are obviously still conflicting views on how documentation should
> be handled. I have decided to step away from this entirely and concentrate
> my volunteer efforts elsewhere.
>
> Regards
> Keith
>
> [orcmid]
> I don't think there are conflicting views. There have been considerations
> of a few approaches and ways of satisfying ASF sensibilities. There are
> some concerns about ASF sensibilities with regard to carrying
> "foreign"-licensed materials in ASF repositories.
>
> For example, one option would be going the AOOAuthors route and hosting
> that effort on GitHub.
>
> The alternative Keith favors involves hosting within the AOO project in a
> manner that does not conflict with ASF sensibilities about licenses. As
> far as I can tell, no one is stopping that being set up and contributors
> recruited.
>
> One caveat. Jean Weber has offered to update her self-published "Getting
> Started" book on AOO to be suitable for AOO 4.1 users (unless 4.2 is
> imminent, I suppose). It would seem valuable to rely on that, including
> assisting her, rather than have duplicate effort inside the AOO project.
> So maybe there should be a different focus for the AOO effort, starting
> with OO 3.2 User Guides.
>
> - Dennis
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
RE: Proposed Process for Documentation
Posted by Dennis Hamilton <or...@msn.com>.
-----Original Message-----
From: Keith N. McKenna <ke...@comcast.net>
Sent: Saturday, January 23, 2021 15:43
To: doc@openoffice.apache.org
Subject: Re: Proposed Process for Documentation
[orcmid] [ ... ]
As there are obviously still conflicting views on how documentation should be handled. I have decided to step away from this entirely and concentrate my volunteer efforts elsewhere.
Regards
Keith
[orcmid]
I don't think there are conflicting views. There have been considerations of a few approaches and ways of satisfying ASF sensibilities. There are some concerns about ASF sensibilities with regard to carrying "foreign"-licensed materials in ASF repositories.
For example, one option would be going the AOOAuthors route and hosting that effort on GitHub.
The alternative Keith favors involves hosting within the AOO project in a manner that does not conflict with ASF sensibilities about licenses. As far as I can tell, no one is stopping that being set up and contributors recruited.
One caveat. Jean Weber has offered to update her self-published "Getting Started" book on AOO to be suitable for AOO 4.1 users (unless 4.2 is imminent, I suppose). It would seem valuable to rely on that, including assisting her, rather than have duplicate effort inside the AOO project. So maybe there should be a different focus for the AOO effort, starting with OO 3.2 User Guides.
- Dennis
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Proposed Process for Documentation
Posted by "Keith N. McKenna" <ke...@comcast.net>.
On 1/23/2021 2:25 AM, Robert Farrell wrote:
> Keith,
>
> I’d be glad to lend a hand with the Getting Started guides. Tell me what you need and how you need it. My platform is MacBook Pro MacOS 11.1 (Big Sur).
>
> Thanks,
>
> Robert
>
> Robert Farrell
> robertfarrell@embarqmail.com
>
>
>
>> On Jan 21, 2021, at 3:25 PM, Keith N. McKenna <ke...@comcast.net> wrote:
>>
>> On 1/15/2021 1:01 AM, F Campos Costero wrote:
>>> 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
>>>
>>
>> Yes I did. In fact all the revisions of the proposal were done using my
>> GitHub account and it worked quite well. It will offer to open the
>> binary file in the external application. You are correct that it does
>> not handle a diff, but that is not why I was suggesting using it. It was
>> simply as this is the version control system that the project has chosen
>> to use and trying to implement anything different would require yet
>> another VM for the project and the incumbent overhead of finding
>> volunteers with the necessary skills to maintain it.
>>
>> As I am seeing no other comments from the documentation team I am
>> planning on writing this attempt off as one more failure on my part.
>>
>> I will continue on my own to attempt to get a usable 4.1.x and 4.2.x
>> Getting Started guide completed. Any help in getting these done will be
>> greatly appreciated.
>>
>> Regards
>> Keith
>>
>>> On Thu, Jan 14, 2021 at 10:26 AM Keith N. McKenna <ke...@comcast.net>
>>> wrote:
>>>
>>>> On 1/13/2021 6:17 PM, Dennis Hamilton wrote:
>>
As there are obviously still conflicting views on how documentation
should be handled. I have decided to step away from this entirely and
concentrate my volunteer efforts elsewhere.
Regards
Keith
Re: Proposed Process for Documentation
Posted by marcia wilbur <ai...@well.com>.
Robert, this is great news! I'm making progress with the GNU Linux guides.
----- Original Message -----
From: "Robert Farrell" <ro...@embarqmail.com>
To: doc@openoffice.apache.org
Sent: Saturday, January 23, 2021 12:25:30 AM
Subject: Re: Proposed Process for Documentation
Keith,
I’d be glad to lend a hand with the Getting Started guides. Tell me what you need and how you need it. My platform is MacBook Pro MacOS 11.1 (Big Sur).
Thanks,
Robert
Robert Farrell
robertfarrell@embarqmail.com
> On Jan 21, 2021, at 3:25 PM, Keith N. McKenna <ke...@comcast.net> wrote:
>
> On 1/15/2021 1:01 AM, F Campos Costero wrote:
>> 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
>>
>
> Yes I did. In fact all the revisions of the proposal were done using my
> GitHub account and it worked quite well. It will offer to open the
> binary file in the external application. You are correct that it does
> not handle a diff, but that is not why I was suggesting using it. It was
> simply as this is the version control system that the project has chosen
> to use and trying to implement anything different would require yet
> another VM for the project and the incumbent overhead of finding
> volunteers with the necessary skills to maintain it.
>
> As I am seeing no other comments from the documentation team I am
> planning on writing this attempt off as one more failure on my part.
>
> I will continue on my own to attempt to get a usable 4.1.x and 4.2.x
> Getting Started guide completed. Any help in getting these done will be
> greatly appreciated.
>
> Regards
> Keith
>
>> On Thu, Jan 14, 2021 at 10:26 AM Keith N. McKenna <ke...@comcast.net>
>> wrote:
>>
>>> On 1/13/2021 6:17 PM, Dennis Hamilton wrote:
>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Proposed Process for Documentation
Posted by Robert Farrell <ro...@embarqmail.com>.
Keith,
I’d be glad to lend a hand with the Getting Started guides. Tell me what you need and how you need it. My platform is MacBook Pro MacOS 11.1 (Big Sur).
Thanks,
Robert
Robert Farrell
robertfarrell@embarqmail.com
> On Jan 21, 2021, at 3:25 PM, Keith N. McKenna <ke...@comcast.net> wrote:
>
> On 1/15/2021 1:01 AM, F Campos Costero wrote:
>> 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
>>
>
> Yes I did. In fact all the revisions of the proposal were done using my
> GitHub account and it worked quite well. It will offer to open the
> binary file in the external application. You are correct that it does
> not handle a diff, but that is not why I was suggesting using it. It was
> simply as this is the version control system that the project has chosen
> to use and trying to implement anything different would require yet
> another VM for the project and the incumbent overhead of finding
> volunteers with the necessary skills to maintain it.
>
> As I am seeing no other comments from the documentation team I am
> planning on writing this attempt off as one more failure on my part.
>
> I will continue on my own to attempt to get a usable 4.1.x and 4.2.x
> Getting Started guide completed. Any help in getting these done will be
> greatly appreciated.
>
> Regards
> Keith
>
>> On Thu, Jan 14, 2021 at 10:26 AM Keith N. McKenna <ke...@comcast.net>
>> wrote:
>>
>>> On 1/13/2021 6:17 PM, Dennis Hamilton wrote:
>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Proposed Process for Documentation
Posted by "Keith N. McKenna" <ke...@comcast.net>.
On 1/15/2021 1:01 AM, F Campos Costero wrote:
> 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
>
Yes I did. In fact all the revisions of the proposal were done using my
GitHub account and it worked quite well. It will offer to open the
binary file in the external application. You are correct that it does
not handle a diff, but that is not why I was suggesting using it. It was
simply as this is the version control system that the project has chosen
to use and trying to implement anything different would require yet
another VM for the project and the incumbent overhead of finding
volunteers with the necessary skills to maintain it.
As I am seeing no other comments from the documentation team I am
planning on writing this attempt off as one more failure on my part.
I will continue on my own to attempt to get a usable 4.1.x and 4.2.x
Getting Started guide completed. Any help in getting these done will be
greatly appreciated.
Regards
Keith
> On Thu, Jan 14, 2021 at 10:26 AM Keith N. McKenna <ke...@comcast.net>
> wrote:
>
>> On 1/13/2021 6:17 PM, Dennis Hamilton wrote:
Re: Proposed Process for Documentation
Posted by F Campos Costero <fj...@gmail.com>.
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 <ke...@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 <ke...@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-unsubscribe@openoffice.apache.org
> > For additional commands, e-mail: doc-help@openoffice.apache.org
> >
>
>
Re: Proposed Process for Documentation
Posted by "Keith N. McKenna" <ke...@comcast.net>.
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 <ke...@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-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
RE: Proposed Process for Documentation
Posted by Dennis Hamilton <or...@msn.com>.
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
-----Original Message-----
From: Keith N. McKenna <ke...@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-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org