[libreoffice-documentation] Wiki cleanup
I've started to revise and organize parts of the documentation wiki, starting with things I think will be uncontroversial. I figure that this is a good thing to do while I'm new, since it's obvious to me what is confusing or hard to find, but do speak up if I get carried away. Two major problems that stick out to me: 1. There is a large but incomplete duplication of content between the TDF wiki, the documentation website, and the main website. I think there needs to be a discussion about what should go where. 2. There seems to be two very different kinds of content on the TDF documentation team sub-wiki: pages for users, and pages for the documentation team. On the other hand, there is also miscellaneous info for users scattered around other parts of the wiki. Currently it doesn't look like it would be trivial to move the all the users-facing wiki pages to the documentation website, so perhaps as a temporary solution we could make a separate section or subsection on the wiki to collect everything together. I'll think about what to name this hypothetical section and wait for other opinions before I do anything. --Kenneth -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org 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
Re: [libreoffice-documentation] simplifying documentation
Hi Cor, Just to be clear, I was not expressing problems with the Help files. In fact, I was not even aware that they exist when I wrote this. Thank you! Cathy On 7/27/2017 3:52 AM, Cor Nouws wrote: Hi Cathy, Dave wrote on 26-07-17 11:26: On 26.07.2017 03:08, Cathy Crumbley wrote: It can take many words to explain a relatively simple concept when wording in the program itself is unclear or even misleading. Is there a mechanism for giving feedback to the developers about changing some of the wording within the program? If so, how does that work? As to raising the issue of unclear or even misleading wording in the help files, my _*guess*_ would be, that for very specific entries in the help files you could raise an issue on Bugzilla: https://wiki.documentfoundation.org/QA/BugReport or contact Oliver for assistance. Indeed issues are the proper way to suggest better wording. You may add needsUXEval to the keywords field, so that the UX team, deciding on improvements, finds your proposal easily. thanks for your help! Cor -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org 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
Re: [libreoffice-documentation] simplifying documentation
Hi Olivier, Thanks again for the responses. If this has been a problem for a while, I am puzzled about why it has not been fixed. Are you aware of a reason why the download page cannot be re-worded now? To be clear, what are you saying is the best source of information for people who are new to this and want to learn about the overall LibreOffice project? Are you saying that the wiki is not useful because so much work needs to be done on it? As long as I am asking questions, here is one more: What is the Pootle server? Cheers, Cathy On 7/27/2017 3:29 PM, Olivier Hallot wrote: Hello Cathy Em 27/07/2017 15:16, Cathy Crumbley escreveu: Hi Olivier, (snip) Finally, I downloaded the file and realized what I have been missing. Perhaps I am a dunderhead but if I missed the Help files, perhaps others have. I would strongly recommend that the download page be clearer about what the file contains. Can this feedback be passed on to the appropriate people or should I submit it somewhere? No dunderhead at all and thanks again for raising the issue. This is an old issue and people keep bypassing the download of the Help. I know the Help is not downloaded because it pulls a string in the forums and mailing lists on very basic subjects, typical of those who do not access a Help, for whatever reason. On another note, I have been wondering how to find information about the project as a whole. Then I looked at the blog post you linked to and found pages with some of the information I have been looking for. I would like to suggest that new members like me be referred to that site as an introduction to the LibreOffice project. We keep a wiki for that purpose. But it requires permanent reordering and addition/deletion/update of hundreds of pages, permanently. We also have our main website (www.libreoffice.org) with information on the project. By the way, I noticed an archived tender (July 2016) to redesign the download page. Does anyone know if that means that it has already been redesigned and that it will not be changed for a while? The download page has been reworked recently. Kind regards Thanks again. Cathy On 7/26/2017 7:00 PM, Olivier Hallot wrote: Hi Cathy Em 25/07/2017 22:08, Cathy Crumbley escreveu: What is the relationship between Help and the Guides? It sounds like they are on two separate tracks. Are they duplicating information independently? I'm glad you raised this question. Yes they are separated tracks and contents duplication is a fact, at least partially. Help pages are instance of web on-line pages, and guides are instances of printed books. Different form factors for different usage. The Help is part of the software and is invoked when you press F1 or click on the Help button in a dialog. Because it is part of the application, the following applies * It is a flat and factual description of the feature, eventually with examples and use cases. Its objective is to help users to get the job done. * The Help pages are translated into all released languages (currently 68 languages). * It must contain the most accurate information on the features of the software. * Is must be indexed for easy referencing and search. However, not everything is actually true... * Translation of the Help depends on volunteers, which have limited time available for the task. This however does not prevent us from releasing new versions, but with unfinished translations in some cases. * A significant part of the Help is also a user guide, which overlaps with the current Guides we have. However, editing Help pages and inserting it into the Help system is way more complex than writing/updating a text document in Writer, as we do for the guides. I'd like to discuss the contents of the Help User Guide and see if the Help system needs to get leaner. * The help system is poorly illustrated, almost everything is textual with very few images and no videos. * Because of the way the software is developed, LibreOffice developers don't write software specification paperwork, and new features mushrooms in the code, with no documentation or help page associated (with rare and much appreciated exceptions). Many new developments as well as changes in the user interface are not documented yet in the Help, which means the Help is lagging with respect to the software. We are however collecting these gaps in a list and looking for volunteers to write about. What prevents us to evolve with the Help, and find something more easy for volunteers to contribute? * we must absolutely preserve its current contents and translations process, people don't like useless rework. * We don't have a replacing technology that can in a finger snap, make all the legacy content available to a more user-friendly editing process. My last blog post addresses the issue. https://goo.gl/j3DVAG There will be a workshop in Rome, at our LibreOffice Conference where we will discuss these issues and more. I hope to meet all
Re: [libreoffice-documentation] simplifying documentation
Hello Cathy Em 27/07/2017 15:16, Cathy Crumbley escreveu: > Hi Olivier, > (snip) > Finally, I downloaded the file and realized what I have been missing. > > Perhaps I am a dunderhead but if I missed the Help files, perhaps others > have. I would strongly recommend that the download page be clearer about > what the file contains. Can this feedback be passed on to the > appropriate people or should I submit it somewhere? > No dunderhead at all and thanks again for raising the issue. This is an old issue and people keep bypassing the download of the Help. I know the Help is not downloaded because it pulls a string in the forums and mailing lists on very basic subjects, typical of those who do not access a Help, for whatever reason. > On another note, I have been wondering how to find information about the > project as a whole. Then I looked at the blog post you linked to and > found pages with some of the information I have been looking for. I > would like to suggest that new members like me be referred to that site > as an introduction to the LibreOffice project. We keep a wiki for that purpose. But it requires permanent reordering and addition/deletion/update of hundreds of pages, permanently. We also have our main website (www.libreoffice.org) with information on the project. > > By the way, I noticed an archived tender (July 2016) to redesign the > download page. Does anyone know if that means that it has already been > redesigned and that it will not be changed for a while? The download page has been reworked recently. Kind regards > > Thanks again. > > Cathy > > On 7/26/2017 7:00 PM, Olivier Hallot wrote: >> Hi Cathy >> >> Em 25/07/2017 22:08, Cathy Crumbley escreveu: >>> What is the relationship between Help and the Guides? It sounds like >>> they are on two separate tracks. Are they duplicating information >>> independently? >> I'm glad you raised this question. >> >> Yes they are separated tracks and contents duplication is a fact, at >> least partially. Help pages are instance of web on-line pages, and >> guides are instances of printed books. Different form factors for >> different usage. >> >> The Help is part of the software and is invoked when you press F1 or >> click on the Help button in a dialog. >> >> Because it is part of the application, the following applies >> >> * It is a flat and factual description of the feature, eventually with >> examples and use cases. Its objective is to help users to get the job done. >> >> * The Help pages are translated into all released languages (currently >> 68 languages). >> >> * It must contain the most accurate information on the features of the >> software. >> >> * Is must be indexed for easy referencing and search. >> >> However, not everything is actually true... >> >> * Translation of the Help depends on volunteers, which have limited time >> available for the task. This however does not prevent us from releasing >> new versions, but with unfinished translations in some cases. >> >> * A significant part of the Help is also a user guide, which overlaps >> with the current Guides we have. However, editing Help pages and >> inserting it into the Help system is way more complex than >> writing/updating a text document in Writer, as we do for the guides. I'd >> like to discuss the contents of the Help User Guide and see if the Help >> system needs to get leaner. >> >> * The help system is poorly illustrated, almost everything is textual >> with very few images and no videos. >> >> * Because of the way the software is developed, LibreOffice developers >> don't write software specification paperwork, and new features mushrooms >> in the code, with no documentation or help page associated (with rare >> and much appreciated exceptions). Many new developments as well as >> changes in the user interface are not documented yet in the Help, which >> means the Help is lagging with respect to the software. We are however >> collecting these gaps in a list and looking for volunteers to write about. >> >> What prevents us to evolve with the Help, and find something more easy >> for volunteers to contribute? >> >> * we must absolutely preserve its current contents and translations >> process, people don't like useless rework. >> >> * We don't have a replacing technology that can in a finger snap, make >> all the legacy content available to a more user-friendly editing >> process. My last blog post addresses the issue. >> https://goo.gl/j3DVAG >> >> There will be a workshop in Rome, at our LibreOffice Conference where we >> will discuss these issues and more. I hope to meet all authors involved. >> >> http://conference.libreoffice.org/ >> >> Kind regards >> > -- Olivier Hallot LibreOffice Documentation Coordinator Comunidade LibreOffice Rio de Janeiro - Brasil - Local Time: UTC-03:00 http://tdf.io/joinus -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems?
Re: [libreoffice-documentation] simplifying documentation
Hi Olivier, Thank you for the explanation. It is impressive to see that it is available (in part) in 68 languages. I have been using LibreOffice since last September. In that time, I have barely used Help because it is so hard to find the information I am looking for. Since it seems to offer little value, I have been wondering why so much work has been going into developing it. Then, I read below where you say "Because it is part of the application..." This made no sense since it is not part of the application but rather a website. This made me wonder if I was missing something. So, I went to the download page and noticed that there is a file called "Help for offline use." It is possible that I saw this before but paid no attention because I am always online. Finally, I downloaded the file and realized what I have been missing. Perhaps I am a dunderhead but if I missed the Help files, perhaps others have. I would strongly recommend that the download page be clearer about what the file contains. Can this feedback be passed on to the appropriate people or should I submit it somewhere? On another note, I have been wondering how to find information about the project as a whole. Then I looked at the blog post you linked to and found pages with some of the information I have been looking for. I would like to suggest that new members like me be referred to that site as an introduction to the LibreOffice project. By the way, I noticed an archived tender (July 2016) to redesign the download page. Does anyone know if that means that it has already been redesigned and that it will not be changed for a while? Thanks again. Cathy On 7/26/2017 7:00 PM, Olivier Hallot wrote: Hi Cathy Em 25/07/2017 22:08, Cathy Crumbley escreveu: What is the relationship between Help and the Guides? It sounds like they are on two separate tracks. Are they duplicating information independently? I'm glad you raised this question. Yes they are separated tracks and contents duplication is a fact, at least partially. Help pages are instance of web on-line pages, and guides are instances of printed books. Different form factors for different usage. The Help is part of the software and is invoked when you press F1 or click on the Help button in a dialog. Because it is part of the application, the following applies * It is a flat and factual description of the feature, eventually with examples and use cases. Its objective is to help users to get the job done. * The Help pages are translated into all released languages (currently 68 languages). * It must contain the most accurate information on the features of the software. * Is must be indexed for easy referencing and search. However, not everything is actually true... * Translation of the Help depends on volunteers, which have limited time available for the task. This however does not prevent us from releasing new versions, but with unfinished translations in some cases. * A significant part of the Help is also a user guide, which overlaps with the current Guides we have. However, editing Help pages and inserting it into the Help system is way more complex than writing/updating a text document in Writer, as we do for the guides. I'd like to discuss the contents of the Help User Guide and see if the Help system needs to get leaner. * The help system is poorly illustrated, almost everything is textual with very few images and no videos. * Because of the way the software is developed, LibreOffice developers don't write software specification paperwork, and new features mushrooms in the code, with no documentation or help page associated (with rare and much appreciated exceptions). Many new developments as well as changes in the user interface are not documented yet in the Help, which means the Help is lagging with respect to the software. We are however collecting these gaps in a list and looking for volunteers to write about. What prevents us to evolve with the Help, and find something more easy for volunteers to contribute? * we must absolutely preserve its current contents and translations process, people don't like useless rework. * We don't have a replacing technology that can in a finger snap, make all the legacy content available to a more user-friendly editing process. My last blog post addresses the issue. https://goo.gl/j3DVAG There will be a workshop in Rome, at our LibreOffice Conference where we will discuss these issues and more. I hope to meet all authors involved. http://conference.libreoffice.org/ Kind regards -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org 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
Re: [libreoffice-documentation] Request to join
Hi Kenneth I have registered you in ODFAuthors, you will receive a confirmation mail. Kind regards Olivier Em 26/07/2017 21:32, Kenneth Hanson escreveu: > Hello. Looking to get involved with LibreOffice. My background is in > linguistics, Japanese, and computer science, and I'm currently working as > an assistant English teacher in Japan. > > My C++ skills are too weak for me to immediately participate in > development, but I have some experience writing informational websites and > documents, so I'd like to help with documentation in the meantime. How much > time I have will probably vary wildly throughout the year. > > Please grant me access to ODFAuthors and anywhere else that I can't > register on my own. > > --Kenneth Hanson > -- Olivier Hallot LibreOffice Documentation Coordinator Comunidade LibreOffice Rio de Janeiro - Brasil - Local Time: UTC-03:00 http://tdf.io/joinus -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org 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
