Re: Documentation volunteer - introduction
Hi Nadeem, I am not sure what Keith has in mind for the review process versus publication. Let's wait to hear from him. We are still trying to work out how to do everything and I don't think any changes have been made to the documents on the web site. Since Git cannot generate a diff for these binary files, I am not sure what the best method is to avoid conflicts between multiple reviewers. I think a viable workflow for the moment is to get documents from my fork. You should be able to clone that. You would then have my last version of both the Getting Started guide and the Writer guide. The safest path, if you want to do some editing, might be for you to edit the Writer guide and for Keith to edit the Getting Started guide. If you can push commits to my fork, you could directly push your versions back up. If you cannot directly change my fork, you could send me the revised versions and I will push them. (Would you be willing to make a trivial change to one document from the Writer guide, adding a space at the end, and try to push that to my fork?) When all the editing is done, I can make a pull request for Keith to move the docs to the Apache repo and do whatever publication process he has in mind. With respect to this question: * "Also, what sort of changes/review should I be making? I* *understand there are formatting and probably typo-related things to workon, but is there some sort of guide to look at as reference?"* No, there is not a guide. I have invented a process as I went along. I will try to explain that here. - I apply the template AOOdoc.ott that is available in the Templates branch of the Apache repo. I use the template changer extension to do this. - I change all product references from OpenOffice.org to either OpenOffice or Apache OpenOffice. - The abbreviation OOo is changed to AOO - I update all text and figures to reflect current features and appearance. For example, images of dialogs that include the old OpenOffice.org name are replaced with an image of the latest dialog. I also added a lot of references to the Sidebar and provided images where that was appropriate. - Check that formatting is applied via styles instead of hard formatting, using the styles from the template whenever possible and minimize the number of styles used. (The template implements a set of styles whose names start with OOo.) The idea is to simplify the formatting in the hopes of making the translation to the Wiki easier. The main changes were using the character style OOoMenuPath for all cases of bold text, eliminating the style OOoStrongEmphasis and hard formatting, and using OOoEmphasis instead of hardcoded italic. - Checking all numbered lists for proper numbering. Applying the new template seems to mess up numbered lists. - Check for multiple spaces in inappropriate places using Find & Replace - Search for stray areas of Liberation Sans font from the old template that somehow survive the template change. - Remove text that references archaic technology, e.g. faxes, or literature. I didn't do this in every case. - Update web page links. - Spell check. (Some documents were written in non-US English and I don't think I always changed those spellings.) The hardest part is updating features. You just have to know the software. I am not an OpenOffice guru but I relied on 10+ years of helping on the forum. There are also instances of factual errors and catching those is also tough. I really hope someone else can update the Impress and Draw guides! Francis On Thu, Jun 17, 2021 at 12:57 AM Nadeem Patel wrote: > Hi Francis, > > I see there are review and published, so I now I understand which have been > reviewed and published already and which need to be reviewed. While this is > something I might need to actually be concerned about, I am curious to know > how the files receive a published or review on GitHub > (ex. Published/AOO41GS1.odt → Getting-Started-Guide/AOO41GS1.odt > or Review/AOO41GS12.odt → Getting-Started-Guide/AOO41GS12.odt). I'm asking > because I would like to get a better idea of the repo and how things change > there and how it appears on the actual website. My other questions are a > bit more straightforward. Should I download the file that is listed as > "Review..." and make changes or is there a different place I should be > getting the files? Also, what sort of changes/review should I be making? I > understand there are formatting and probably typo-related things to work > on, but is there some sort of guide to look at as reference? I know you > said we can just pick up something and get started, but I also don't want > to go about things incorrectly, so I thought I should ask. Thanks for your > help! > > Best, > > Nadeem > > On Wed, Jun 16, 2021 at 11:07 PM F Campos Costero > wrote: > > > Hi Nadeem, > > It looks like Keith has been restructuring the repo. If you click on the > > link to the commit
Re: Documentation volunteer - introduction
Hi Francis, I see there are review and published, so I now I understand which have been reviewed and published already and which need to be reviewed. While this is something I might need to actually be concerned about, I am curious to know how the files receive a published or review on GitHub (ex. Published/AOO41GS1.odt → Getting-Started-Guide/AOO41GS1.odt or Review/AOO41GS12.odt → Getting-Started-Guide/AOO41GS12.odt). I'm asking because I would like to get a better idea of the repo and how things change there and how it appears on the actual website. My other questions are a bit more straightforward. Should I download the file that is listed as "Review..." and make changes or is there a different place I should be getting the files? Also, what sort of changes/review should I be making? I understand there are formatting and probably typo-related things to work on, but is there some sort of guide to look at as reference? I know you said we can just pick up something and get started, but I also don't want to go about things incorrectly, so I thought I should ask. Thanks for your help! Best, Nadeem On Wed, Jun 16, 2021 at 11:07 PM F Campos Costero wrote: > Hi Nadeem, > It looks like Keith has been restructuring the repo. If you click on the > link to the commit that starts with 8928b59 (there is a link on the right > just above the file names) you can see that the files were all moved into a > single folder. > > In case you cannot see the link. the URL is Move all files to > Getting-Started-Guide · apache/openoffice-docs@8928b59 · GitHub > < > https://github.com/apache/openoffice-docs/commit/8928b59a4295ca79d5ee49ae40f9656be54c1f05 > > > > Please let me know if there is anything I can do to help you get started on > something. I know it is hard to know where to start. There is no one to > assign tasks, so a new person has to find something for themself or help > with one of the few ongoing efforts.. I simply got copies of the user > guides and started editing. Only a few people have edited any documentation > lately, so you are unlikely to step on any toes. > Francis > > On Wed, Jun 16, 2021 at 6:29 PM Nadeem Patel > wrote: > > > Hello, > > > > I just wanted to follow up and get some clarification. When I go to > > > > > https://github.com/apache/openoffice-docs/tree/Getting-Sarted-Guide/Getting-Started-Guide > > , > > I don't see a published and review folder. Am I missing something? > > > > Best, > > > > Nadeem > > > > > > > > > > On Thu, Jun 3, 2021 at 4:19 PM Keith N. McKenna < > keith.mcke...@comcast.net > > > > > wrote: > > > > > On 2021-06-02 14:05, F Campos Costero wrote: > > > Greetings Francis and Comments in line. > > > > > > > Hi Nadeem, > > > > What I have been working on for a while now is updating the user > > guides. > > > > The old guides are available at [1]. Keith has set up a Git > repository > > > [2] > > > > where a branch is dedicated to each guide. I forked that repository > [3] > > > and > > > > I have done initial revisions of the Getting Started guide and the > > Writer > > > > guide. I am slowly working my way through the Calc guide and I am > about > > > > half done with that. As far as I know, only the first three chapters > of > > > the > > > > Getting Started guide (A0041GS1.odt - A0041GS3.odt) have been > reviewed > > by > > > > anyone else. If you are willing to jump into reviewing the other > > > chapters, > > > > there is plenty to do. Each guide is a few hundred pages and each > > chapter > > > > is typically 20 - 40 pages. > > > > > > I apologize for that Francis. Some things in my personal life came up > in > > > mid-May that took a lot of my time. I am at this point back working on > > > reviewing Chapter 4 of the getting started guide. > > > Some new information on who the Copyright holder should be listed as on > > > the copyright page. It should be The Apache Software Foundation.Also > > > traditionally we follow the American English use headline style > > > capitalization. Follow American English capitalization guidelines for > > > headings. Capitalize the first letter of every word except > conjunctions, > > > articles, prepositions of fewer than four letters, and the "to" in > > > infinitives. I am doing this as I review the the chapters of the > > > Getting Started Guide. > > > > > > > The documentation process was dormant for quite a while and Keith has > > > been > > > > trying hard to revive it. We have just recently started to use Git > and > > we > > > > may well have to change the process as we learn how to work with it. > > Are > > > > you familiar with Git? We only use the most basic features. > > > > > > I am making some changes know that I believe will help with the process > > > of review and merging. Instead of using review and release folders for > > > each branch I am adding Guide Folders in Main that will always hold the > > > currently published complete guide as well as the chapters.This should > > > make the review and merge process
