Hazel has covered some of the important points I would have made. I'll get back with a more detailed reply next week, after discussion with techwriting colleagues at the OpenHelp Conference this coming weekend.
At this point, I'll address only one point: published ODTs are essential for translators, among others, and since an ODT is a precursor to a PDF, publishing them as well takes only trivial effort. Leaving the ODT link off the website might be reasonable (for end-user consumption), but that is different from not publishing the ODT on the wiki and making it available through the Alfresco media front-end. --Jean On Sat, Aug 4, 2012 at 10:42 AM, David Nelson <[email protected]> wrote: > Hi Jean, > > On Sat, Aug 4, 2012 at 5:48 PM, Jean Weber <[email protected]> wrote: >> BTW, this wiki page includes a diagram of the workflow used by >> ODFAuthors for many years for docs production. The descriptive text is >> a bit out of date (especially info on naming convention) and not >> relevant to Alfresco (again, naming convention), but the general flow >> is one I think should be adapted to work with the Alfresco tools. >> https://wiki.documentfoundation.org/Documentation/Development#First_steps_with_the_Documentation_team > > OK, the workflow we originally set-up on Alfresco is a bit like Snakes > & Ladders. The doc start in the "Drafts" folder. A considered-ready > draft gets approved and goes forward to the "Review" folder. A > reviewer proofreads it, and either it gets approved and gets moved > forward to the "Publish" folder, or it gets rejected and goes back to > "Drafts". The act of approval or rejection (it wasn't always actually > used) was to click on one of two menu options in the right-hand menu > that appears when your mouse pointer hovers over the document. The > result was that Alfresco would move the document to one folder or the > other. > > When the doc actually lands in the Publish folder, the bells sound and > the doc gets published. > > This is a manual process in which a team member downloads the document > from Alfresco, generates a PDF from it, has to log into the wiki, > upload the documents, edit/update the links in the wiki page with the > published documents list > (http://wiki.documentfoundation.org/Documentation/Publications). Then > the team member has to log into libreoffice.org and update the docs > download page (http://www.libreoffice.org/get-help/documentation/) > with the new links from the wiki. > > Note: some of the tracking functionality is done within the document, > using LibreOffice's changes tracking and comments features. I have > missed out on the "Feedback" folder (insert additional snake/ladder). > > Questions: Is there a real need for more than Draft/Review/Publish > folders? What is the real value of the Feedback folder? Could we > usefully just eliminate it and simplify things? > > Question: The workflow described on the wiki involves 4 roles - > Writer, Reviewer, Editor, Publisher. Could we usefully simplify that > to Writer and Reviewer? Editor and Publisher could potentially be > eliminated, because of my file-naming suggestion below. > > Suggestion: On Alfresco, you could usefully revise the file-naming > conventions. Keep the conventions as regards the title of the manual. > But remove the version info from the filename. Instead, decide what > fields you want to have in the meta data of each file, and store the > version info in there only. The advantages I'd see are discussed > below. > > Suggestion/thoughts: I guess this is stating the obvious, but > ultimately the team needs to choose between the current ODFAuthors > tool and Alfresco. Having both described in > http://wiki.documentfoundation.org/Documentation/Publications > *probably* discourages a lot of potential contributors because of the > complexity of the functioning. IMHO, even the workflow on either tool > is *possibly* more complex than necessary. Either move to Alfresco > (hosted either on http://alfresco.libreoffice.org or on > http://odfauthors.org) or stay with the Plone tool? OK, irrelevant to > the current thread. Forget I said that... ;-) > > Possible different solution > =================== > > Have 2 folders for each manual: "Work-in-progress" and "Published". > > All work gets done on the file in "Work-in-progress" and there is only > ever one file for each chapter of a manual in the "Work-in-progress" > folder. > > Alfresco's versioning system updates the version number of the file > each time someone uploads some work done (via "Upload new version" > under "More..."). One can easily roll back to a previous version > number if necessary, or download an old version number if desired. > > Each worker enters a comment in the Alfresco comment box when > uploading, stating the work done (and/or in a comment field in the > document meta data). > > The same file is used even when work starts on updating a chapter to > take account of a new version of LibreOffice. In this case, the > LibreOffice version number is updated by a team member in the file's > meta data. You don't have to worry about incrementing any file version > number in the meta data, because Alfresco is handling the version > numbering. > > When the file is finally publication-ready, one uploads it ("Upload > new version" in "More...") as a new version of a file of the same name > already existing in the "Published" folder. That existing file is > already linked-to on the wiki and on libreoffice.org (the link comes > from the public browser on http://media.libreoffice.org), so there is > nothing to update and no further action is necessary (except > generating a new PDF file for the entire manual). > > The same naming simplification for PDF files would eliminate the same > wiki/libreoffice.org drudgery as for the ODT files. > > On the wiki page, eliminate the publication dates (removing more > arduous manual work). Don't most people just want to download the > latest available version? One can always just post on the blog when > one publishes a new version, if one wants to. > > Possible further simplification > ====================== > > Just publish PDF files as the final deliverable to the public - one > PDF file for each manual. > > Personally, I *never* consume documentation in .odt form, I *always* > prefer an entire manual in one PDF file. For me, a .odt file is a > working medium not a consumption medium. > > A PDF file can be opened on almost any computing device. A .odt file > specifically requires LibreOffice to be installed. > > Conclusion > ======== > > OK, I think I've covered everything that comes to mind right at this > moment, but I'm trying to find ways to reduce the workload and to > simplify contribution, as this will take weight off current team > members and possibly encourage more people to volunteer. > > Responses and counter-suggestions? > > -- > David Nelson > > -- > Unsubscribe instructions: E-mail to [email protected] > Problems? > http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ > Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette > List archive: http://listarchives.libreoffice.org/global/documentation/ > All messages sent to this list will be publicly archived and cannot be deleted > -- Unsubscribe instructions: E-mail to [email protected] Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette List archive: http://listarchives.libreoffice.org/global/documentation/ All messages sent to this list will be publicly archived and cannot be deleted
