OpenSUSE Docs Meeting 8th July 2021
The documentation team (https://t.me/opensuse_docs) is having a meeting later today at 19:00 UTC on meet.opensuse.org/docs! If you have requests about documentation (https://github.com/openSUSE/openSUSE-docs-revamped-temp/) or want to contribute, do drop by! 🤗
Hi On 7/8/21 7:10 PM, Luna Jernberg wrote:
The documentation team (https://t.me/opensuse_docs) is having a meeting later today at 19:00 UTC on meet.opensuse.org/docs! If you have requests about documentation (https://github.com/openSUSE/openSUSE-docs-revamped-temp/) or want to contribute, do drop by! 🤗
I can't contribute because the meeting is in the middle of the night but I have a couple of questions related to the documentation talk. The first is related to the wiki, it was mentioned in the conference talk that you would like to see all documentation removed from the wiki. Personally I have contributed a small amount to the ARM section of the wiki and have extensively used the documentation there. I really don't think that the approach mentioned in the talk of just removing all documentation from the wiki if people don't work to move there documentation to where you want it, to me this seems like throwing away peoples hard work and is only likely to make people upset instead I think you need to work with the people still using the wiki to help them migrate there work and make sure that it is simple enough for them to continue updating there documentation as they need to. Our wiki has timestamps so its pretty easy to see which areas are still worked on regularly and properly up to date. Maybe a better approach is as documentation from the doc team replaces docs from the doc team you can remove the page content and replace it with a link to the new documentation. At the same time i'm not saying we should keep wiki pages that are obviously incorrect they can go but there is also a middle ground where for pages that haven't been covered by the docs team and that we are unsure how accurate they are where we can place a banner at the top of the page to say we haven't verified that the information on this page is still correct (sometimes incorrect documentation can still get you along way and its better then nothing if your aware its not 100% accurate). Its also worth noting the wiki still has alot of non user related documentation that is still very much correct such as the board and packaging documentation and I don't think it makes sense to move that into the user docs. As a second question we have some fantastic documentation already available already at https://doc.opensuse.org/ how do you plan to integrate this into the new documentation because it really has spent to long suffering from people simply not knowing about it. Cheers -- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B
Hi Simon, Thanks for this message and your reply to me. I'll answer to your -- much appreciated -- reply as soon as possible. As for this message:
For the talk we had to compromise a bit (too much?) on conceptual precision to make things more provocative. Let me repair this now. There are two kinds of contents that need to be distinguished: (Clashing contents) Contents that outright contradict the revamped docs or brush a picture which, if taken together with the picture brushed by the revamped docs, generate an incoherence / un-actionable proposition for the end user (Non-clashing contents). The opposite of the previous. I / we take no issue with Non-clashing contents. Clashing contents is a different story. Not earlier than yesterday, by contrast, I had to tell a Reddit user to not look at the Wikis for configuring their Nvidia driver, and to use the revamped docs instead, on account of the latter providing a peer-reviewed, reliable way of setting up Nvidia acceleration that survives kernel updates. What about your better approach? It naturally leads to a characterization footwork: we need to "tag" clashing contents on the wikis depending on whether the contents are "ready to merge to the new docs", "likely mergeable after hotfixing", "unlikely mergeable", etc. Been there, done that: https://etherpad.opensuse.org/p/wiki-pages-reporting. I don't know about the other contributors to the revamped docs, but I am using this outcome whenever I am looking into adding something to our Table of Contents that overlaps with some wiki clashing contents. But as you can guess it takes a great deal of time and effort to entirely review the wikis to assess their quality in a way that would lead to the tagging I am talking about. An amount of time I cannot afford to spend right now, even if I'd be glad if someone spent it for the Greater Good. So in a nutshell: If people want to help us tag clashing wiki contents, awesome; otherwise the most promising approach as far as I can see is to migrate contents to the revamped docs and indeed label migrated clashing contents with a thick red font (we'll do that once your revamped docs has reached Beta).
Ab-so-lu-te-ly. I hope what I have written above clarifies.
doc.opensuse.org is Leap-centric and does not provide recommendations. We lean toward a more TW-centric docs, that does take recommendation and best-practice at heart. Our current strategy is to: - take everything from doc-o-o when it fits our Table of Contents - boil down to the essentials if possible - add recommendations when valuable - reference the rest, especially in cases where user can get to docs-o-o for more details. To conclude I am not saying I / we have done a perfect job as far as migrating clashing wiki contents and building on / referencing docs-o-o contents, but that's we we're trying to do. How do you like this approach? See you later, Adrien
Hi On 7/8/21 7:10 PM, Luna Jernberg wrote:
The documentation team (https://t.me/opensuse_docs) is having a meeting later today at 19:00 UTC on meet.opensuse.org/docs! If you have requests about documentation (https://github.com/openSUSE/openSUSE-docs-revamped-temp/) or want to contribute, do drop by! 🤗
I can't contribute because the meeting is in the middle of the night but I have a couple of questions related to the documentation talk. The first is related to the wiki, it was mentioned in the conference talk that you would like to see all documentation removed from the wiki. Personally I have contributed a small amount to the ARM section of the wiki and have extensively used the documentation there. I really don't think that the approach mentioned in the talk of just removing all documentation from the wiki if people don't work to move there documentation to where you want it, to me this seems like throwing away peoples hard work and is only likely to make people upset instead I think you need to work with the people still using the wiki to help them migrate there work and make sure that it is simple enough for them to continue updating there documentation as they need to. Our wiki has timestamps so its pretty easy to see which areas are still worked on regularly and properly up to date. Maybe a better approach is as documentation from the doc team replaces docs from the doc team you can remove the page content and replace it with a link to the new documentation. At the same time i'm not saying we should keep wiki pages that are obviously incorrect they can go but there is also a middle ground where for pages that haven't been covered by the docs team and that we are unsure how accurate they are where we can place a banner at the top of the page to say we haven't verified that the information on this page is still correct (sometimes incorrect documentation can still get you along way and its better then nothing if your aware its not 100% accurate). Its also worth noting the wiki still has alot of non user related documentation that is still very much correct such as the board and packaging documentation and I don't think it makes sense to move that into the user docs. As a second question we have some fantastic documentation already available already at https://doc.opensuse.org/ how do you plan to integrate this into the new documentation because it really has spent to long suffering from people simply not knowing about it. Cheers -- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B
Hi Simon, Thanks for this message and your reply to me. I'll answer to your -- much appreciated -- reply as soon as possible. As for this message:
For the talk we had to compromise a bit (too much?) on conceptual precision to make things more provocative. Let me repair this now. There are two kinds of contents that need to be distinguished: (Clashing contents) Contents that outright contradict the revamped docs or brush a picture which, if taken together with the picture brushed by the revamped docs, generate an incoherence / un-actionable proposition for the end user (Non-clashing contents). The opposite of the previous. I / we take no issue with Non-clashing contents. Clashing contents is a different story. Not earlier than yesterday, by contrast, I had to tell a Reddit user to not look at the Wikis for configuring their Nvidia driver, and to use the revamped docs instead, on account of the latter providing a peer-reviewed, reliable way of setting up Nvidia acceleration that survives kernel updates. What about your better approach? It naturally leads to a characterization footwork: we need to "tag" clashing contents on the wikis depending on whether the contents are "ready to merge to the new docs", "likely mergeable after hotfixing", "unlikely mergeable", etc. Been there, done that: https://etherpad.opensuse.org/p/wiki-pages-reporting. I don't know about the other contributors to the revamped docs, but I am using this outcome whenever I am looking into adding something to our Table of Contents that overlaps with some wiki clashing contents. But as you can guess it takes a great deal of time and effort to entirely review the wikis to assess their quality in a way that would lead to the tagging I am talking about. An amount of time I cannot afford to spend right now, even if I'd be glad if someone spent it for the Greater Good. So in a nutshell: If people want to help us tag clashing wiki contents, awesome; otherwise the most promising approach as far as I can see is to migrate contents to the revamped docs and indeed label migrated clashing contents with a thick red font (we'll do that once your revamped docs has reached Beta).
Ab-so-lu-te-ly. I hope what I have written above clarifies.
doc.opensuse.org is Leap-centric and does not provide recommendations. We lean toward a more TW-centric docs, that does take recommendation and best-practice at heart. Our current strategy is to: - take everything from doc-o-o when it fits our Table of Contents - boil down to the essentials if possible - add recommendations when valuable - reference the rest, especially in cases where user can get to docs-o-o for more details. To conclude I am not saying I / we have done a perfect job as far as migrating clashing wiki contents and building on / referencing docs-o-o contents, but that's we we're trying to do. How do you like this approach? See you later, Adrien
participants (3)
-
Adrien Glauser -
Luna Jernberg -
Simon Lees