Minor correction in terminology: "other team members might wish to include some additional identification." Should have read: "other team members might wish to include some additional *or alternative* identification."
On 15/09/2020 16:22, DaveB wrote: > Hi Peter, > > Sounds good. There are a couple of things we need to clarify/finalise; > > Would you be kind enough to put forward a proposal for the file naming > convention to be used for the new workflow/structure? I would be happy > with something like "GS7001 Introducing LibreOffice #1.odt" but you and > other team members might wish to include some additional identification. > It would be good if the team can reach consensus on this asap. > > The 7.0 template needs to be finalised. I will raise a separate thread > about this. > > Officially Retired? Good grief, I don't know how I ever found time for > everyday work :))) > > Best Regards > Dave > > -------- Original Message -------- > From: Peter Schofield [mailto:[email protected]] > Sent: Tuesday, September 15, 2020, 13:32 UTC > To: DaveB > Cc: LibreOffice > Subject: [libreoffice-documentation] Proposal for a change to the > NextCloud workflow > >> Hello Dave >> >> I shall trial the new folders for th Draw Guide 7.0 having just created the >> skeleton of the guide. In other words, creating chapters using the 7.0 >> template and posting in basic information. >> >> It is not so onerous doing the two guides. More than half go the Draw Guide >> is already done. It is called the Impress Guide. Just have to check all >> screen shots to make sure they are OK for the Draw Guide >> >> It keeps me busy now being officially retired. >> >> Regards >> Peter Schofield >> [email protected] >> >> >> >>> On 15 Sep 2020, at 12:46, DaveB <[email protected]> wrote: >>> >>> Hi Peter and Team, >>> >>> My responses are given in-line. >>> >>> -------- Original Message -------- >>> From: Peter Schofield [mailto:[email protected]] >>> Sent: Tuesday, September 15, 2020, 07:50 UTC >>> To: DaveB >>> Cc: LibreOffice >>> Subject: [libreoffice-documentation] Proposal for a change to the >>> NextCloud workflow >>> >>>> Hello Dave and Samantha >>>> >>>> I am with you and agree to the proposed changes, despite having slight >>>> disagreement about folders. >>> >>> That's good to know. I am sure we can find a way to resolve small >>> disagreements. >>> >>>> Work in Progress is definitely the best name for a working folder. Archive >>>> folder fits the bill perfectly. >>> >>> WIP (Work in Progress) seems to be a more accurate description of the >>> folder's purpose and I can think of no good reason to change the Archive >>> folder name. >>> >>>> File naming is the only thing that bugs me. Adding the date into the >>>> filename is not necessary and does make it cumbersome. >>> >>> As I said in my reply to Sam, I am comfortable with whatever file naming >>> convention the team reaches consensus on. >>> >>>> Adding a version number (01,02, etc) to the filename would be insurance IF >>>> someone forgets to move old files into Archive. >>> >>> Sure. Each filename being being unique is the only thing I consider to >>> be important. How that unique identity is defined is for the team to >>> agree upon. >>> >>>> As I am already working on th Impress Guide as a whole, I suppose I have >>>> editorial control??? >>>> >>>> Also, I am starting to work on the Draw Guide, which, in theory, I also >>>> have editorial control??? >>>> >>>> The Draw Guide and Impress Guide are very similar and I am swapping >>>> information between the two guides. >>> >>> Since you have taken on the (IMO somewhat onerous) task of almost >>> single-handedly rewriting those guides, I doubt that anyone would >>> question that you should have editorial control of those guides. >>> >>> I have been asked to take on the role of "Guide Coordinator" for version >>> 7 of the Getting Started Guide, but I have no intention (or ability) to >>> single-handedly rewrite all the chapters for that guide. I was very >>> impressed by Steve Fanning's management of the Calc Guide, but I doubt >>> that I will be able to make the same level of commitment to Getting >>> Started Guide. More on this point in the next few days. >>> >>>> Regards >>>> Peter Schofield >>>> [email protected] >>> >>> Best Regards >>> Dave >>> >>>>> On 14 Sep 2020, at 21:09, DaveB <[email protected]> wrote: >>>>> >>>>> Hi Sam, >>>>> >>>>> Many thanks for your input. My responses are given in-line with the >>>>> points in your original message. >>>>> >>>>> On 12/09/2020 21:03, Samantha Hamilton wrote: >>>>>> I think ultimately this is a discussion about versioning and >>>>>> collaboration >>>>>> in a program (NextCloud) that is not a collaborative version control >>>>>> site. >>>>>> I think that simplifying the folder structure would be helpful to >>>>>> organize >>>>>> the iterations of a document, but it would also mean that the file naming >>>>>> convention would be very important for versioning. >>>>> >>>>> Let's move away from the unnecessary complications of file naming and >>>>> versioning. The only important point is that each edit of a chapter file >>>>> is given a unique file name. If having other identifying characters in >>>>> the file name is what the team wants, I am fine with that. >>>>> >>>>> It doesn't matter if this is the first draft of a chapter, or the 50th >>>>> edited review. The file is uploaded to the Feedback/Work in Progress >>>>> folder and if a previous copy of that chapter file exists in the >>>>> Feedback/Work in Progress folder, that previous copy is IMMEDIATELY >>>>> moved to the Archive folder. At any one time there will only ever be one >>>>> (last edited) copy of any chapter file in the Feedback/Work In Progress >>>>> folder of any book and for anyone wishing to review, revise or otherwise >>>>> edit that chapter this is the file they take. >>>>> >>>>>> As far as my understanding goes, we [would] have a process like this: >>>>>> >>>>>> 1. A new/original document is made by a Creator (this person has >>>>>> editorial >>>>>> ‘control’ over said document) >>>>> >>>>> I seem to have missed the memo about "editorial control". >>>>> Does this mean: >>>>> * If I am the first to start work on a chapter for a new version of a >>>>> guide, do I get "editorial control" for just that chapter or all >>>>> chapters for that version of the guide? >>>>> * If I take on the role of Guide Coordinator, do I get "editorial >>>>> control" of that guide? >>>>> >>>>>> 2. When ready for review it is put into the “Feedback” (or “Work in >>>>>> Progress”) folder, with a naming scheme such as: >>>>>> >>>>>> *<guide name abbreviation><version number><chapter number>_<creators >>>>>> initials>_<date of submission>.extension* >>>>>> >>>>>> *For example:* *IG706_AB_1Sept2020.odt* >>>>> >>>>> It's unclear what benefit would be gained from this file naming >>>>> convention. The file will already have a modified date and the >>>>> author/reviewer is already identified in the status sheet and the >>>>> "Contributors" section of the chapter document. As I said above, "If >>>>> having other identifying characters in the file name is what the team >>>>> wants, I am fine with that". >>>>> >>>>>> 3. A Reviewer downloads a copy (leaving a copy in the folder) and >>>>>> performs >>>>>> edits, reviews, etc. >>>>>> >>>>>> 4. When complete, the Reviewer uploads the newly edited file back to the >>>>>> same “Feedback” folder, >>>>> >>>>> Yes and the reviewer IMMEDIATELY moves any previous copy to the Archive >>>>> storage folder. >>>>> >>>>>> with a naming convention such as: >>>>>> *<guide name abbreviation><version number><chapter number>_<creators >>>>>> initials>_<reviewers initials>_<date of submission>.extension* >>>>>> >>>>>> *For example: IG706_AB_CD_2Sept2020.odt* >>>>> >>>>> Please see my previous comments regarding file naming. >>>>> >>>>>> 5. The Creator accepts, confirms, or rejects changes as necessary, then >>>>>> saves this to the “Feedback” folder as a new file, with a naming scheme >>>>>> such as: >>>>>> >>>>>> *<guide name abbreviation><version number><chapter number>_<creators >>>>>> initials>_<date of submission>.extension* >>>>>> >>>>>> *For example: IG706_AB_3Sept2020.odt* >>>>> >>>>> See my previous comments about "editorial control". >>>>> >>>>>> 6. At the end of this cycle, this single folder would contain 3 versions >>>>>> of >>>>>> the created file. And would look like: >>>>>> >>>>>> *IG706_AB_1Sept2020.odt* >>>>>> *IG706_AB_CD_2Sept2020.odt**IG706_AB_3Sept2020.odt* >>>>> >>>>> No. My earlier comment: "At any one time there will only ever be one >>>>> (last edited) copy of any chapter file in the Feedback/Work In Progress >>>>> folder of any book". All other draft and review copies will already be >>>>> in the Archive storage folder. >>>>> >>>>>> And then we repeat the process. All email messages stay the same, and the >>>>>> status spreadsheet stays the same. This would mean that until a chapter >>>>>> is >>>>>> published we all have access to all previous copies, organized by date, >>>>>> and >>>>>> with contributor identification. >>>>> >>>>> My proposal makes no reference to changing anything other than the >>>>> directory structure and the workflow on NextCloud. At all times every >>>>> one of us has access to every file in the Documentation NextCloud >>>>> instance and my proposal will do nothing to change that. >>>>> >>>>>> Then the files go to the Archives? >>>>> >>>>> No. The Archive sub-directory would be a continuous backup store for all >>>>> previous copies. >>>>> >>>>>> Dave, is this the process that you are thinking of? >>>>> >>>>> It seems I did a really poor job of documenting my proposal. >>>>> >>>>>> Or am I misunderstanding the use of the Archive folder? >>>>> >>>>> There is nothing special about the sub-directory having the name >>>>> Archive. It could just as easily be renamed Dump, Backup or any >>>>> meaningful name and still serve the same purpose. >>>>> >>>>>> All the best, >>>>>> Sam. >>>>>> >>>>>> Samantha Hamilton >>>>>> darling docs >>>>>> >>>>>> <http://www.darlingdocs.com> >>>>>> <https://github.com/samanthahamilton>[image: >>>>>> www.linkedin.com/in/shamilton-darlingdocs] >>>>>> <http://www.linkedin.com/in/shamilton-darlingdocs> >>>>> >>>>> Best Regards >>>>> Dave >>>>> >>>>>> On Sat, Sep 12, 2020 at 8:47 AM User <[email protected]> wrote: >>>>>> >>>>>>> Hi Peter, >>>>>>> >>>>>>> I am not particularly concerned about the naming of files, my only real >>>>>>> interest is that there is a simple straight forward and reliable way to >>>>>>> identify the last edition of the file and where a previous edition of >>>>>>> that file exists, it can easily be researched and/or recovered. >>>>>>> All files with any name difference automatically acquire a modified >>>>>>> date, so identification is extremely simple. Inclusion of the author >>>>>>> initials serves no real worthwhile purpose, this identification is >>>>>>> already taken care of in the status sheet and the contributors section >>>>>>> of every guide chapter. Part of the reasoning behind my suggestion that >>>>>>> we all identify our initials to names on the status sheets. >>>>>>> >>>>>>> If we had even a dozen or more regular contributors then a rigorous file >>>>>>> naming regime might serve a useful purpose. >>>>>>> >>>>>>> Having files stored in just 2 sub-directories (sub-folders) eliminates >>>>>>> any possibility of the same file being edited twice. Personally I don't >>>>>>> give a "flying fig" what name the folders are given. If it were up to me >>>>>>> I would name them WIP (Work In Progress) to hold the most recently >>>>>>> edited editions of the files and Archive to hold previously edited >>>>>>> editions. I am yet to be convinced about the value of the Published >>>>>>> folder, but my view on that point is of no importance. >>>>>>> >>>>>>> My one and only motivation is to simplify our workflow. To me >>>>>>> simplification and ease of understanding of our workflow is an important >>>>>>> part of getting and keeping new contributors involved. New contributors >>>>>>> are what the team will always need, because "creaking old geezers" like >>>>>>> you and I who understand how things were done "In the good ol' days" >>>>>>> won't be here forever. >>>>>>> >>>>>>> OK, I've had my 2c ramble. Now I will leave it to the rest of the team >>>>>>> to decide what we do. >>>>>>> >>>>>>> Best Regards >>>>>>> Dave >>>>>>> >>>>>>> PS. I am subscribed, to the list so the private mail is unnecessary :) >>>>>>> >>>>>>> -------- Original Message -------- >>>>>>> From: Peter Schofield [mailto:[email protected]] >>>>>>> Sent: Saturday, September 12, 2020, 10:38 UTC >>>>>>> To: DaveB >>>>>>> Cc: LibreOffice >>>>>>> Subject: [libreoffice-documentation] Proposal for a change to the >>>>>>> NextCloud workflow >>>>>>> >>>>>>>> Hello Dave >>>>>>>> >>>>>>>> Another thought to help in keeping track of files and this comes from >>>>>>> the day when I used to earn money in tech writing. >>>>>>>> >>>>>>>> First draft of a file and its filename use a sequence number and the >>>>>>> creator’s initials, for example IG7005-ManagingGraphicObjects-01-PS.odt. >>>>>>>> First review of a file, the reviewer adds their initials to the >>>>>>> filename, for example IG7005-ManagingGraphicObjects-01-PS-DB.odt. >>>>>>>> >>>>>>>> Second draft of a file, the sequence number increases changing the >>>>>>> filename and the creator adds their initials, for example >>>>>>> IG7005-ManagingGraphicObjects-02-PS.odt. >>>>>>>> Second review of a file, the reviewer adds their initials to the >>>>>>> filename, for example IG7005-ManagingGraphicObjects-02-PS-DB.odt. >>>>>>>> >>>>>>>> When the file is published, the filename does not have a sequence >>>>>>>> number >>>>>>> or any initials added, for example IG7005-ManagingGraphicObjects.odt. >>>>>>>> >>>>>>>> This does give a good indication of which file is which and prevents >>>>>>>> the >>>>>>> wrong file from being edited again. It worked very well for me and a >>>>>>> team >>>>>>> of technical writers. >>>>>>>> >>>>>>>> We will agree to disagree about folder names, but still think Feedback >>>>>>> is the wrong name to use. A Published folder is a definite. >>>>>>>> >>>>>>>> Regards >>>>>>>> >>>>>>>> Peter Schofield >>>>>>>> [email protected] >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>>> On 11 Sep 2020, at 16:18, DaveB <[email protected]> wrote: >>>>>>>>> >>>>>>>>> For the benefit of those who were not part of yesterday's team >>>>>>>>> meeting, >>>>>>>>> or haven't yet read the minutes. I put forward a proposal as per the >>>>>>>>> subject line of this post. >>>>>>>>> >>>>>>>>> A copy of my proposal is available from: >>>>>>>>> https://nextcloud.documentfoundation.org/s/9FqwWK3m6Cy2zHQ >>>>>>>>> The proposal has 5 points together with my rational for the changes. >>>>>>>>> >>>>>>>>> If there are no reasonable objections, I propose to start updating our >>>>>>>>> NextCloud instance on Friday, 18th. September. >>>>>>>>> >>>>>>>>> Best Regards >>>>>>>>> Dave > -- To unsubscribe e-mail to: [email protected] Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/documentation/ Privacy Policy: https://www.documentfoundation.org/privacy
