September 2020 - openSUSE Documentation

[opensuse-doc] Meeting #2
by Adrien Glauser 25 Sep '20

25 Sep '20

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Please find my notes below. If you happen to come across this stuff for the first time don't think the ship has sailed already! Do jump on it if you're interested and think you can help. We are super nice, can play Pirates of the Caribbean main theme and know how to debate with you whether Telegram is good or evil. Have a pleasant weekend, Adrien Meeting #2 | 24th of September - ------------------------- Present: Ivo, Attila, Andrès, Thomas - ------------------------- Couldn't make it but we look forward to seeing you next time guys: - - Mike, Stephan, Lana - ------------------------ Discussed & accepted: - - to focus on improving the learning experience for new users coming to openSUSE distros (Leap, Tumbleed, and microOS) - - to start off with reviewing and testing guidelines for installing and deploying Live USB sessions for Windows 10 users (Rufus no longer works) - - to use videos where videos are good (demos of "how nice and easy it is to setup and use the openSUSE distros + live tutorials of how to set up desktop-level efficient workflows and best practice), and complement areas where they're not so good with text and other media (i.e. step by step precise instructions or "very important to note" issues) - - to consolidate the current non-technical documentation (i.e. wikis) with already existing contents (consider " https://github.com/cb400f/opensuse-guide.org" deployed at " https://opensuse-guide.org/") should the author be willing to help - - to get inspiration from the Arch Wiki as a quickly editable knowledge base (I am commenting now: probably as far as troubleshooting is concerned, while still focussing on what just works since all the details and technical background will be available from the Arch wiki anyway) - - to seed a "starting" workflow (see Homework below) - ------------------------ Homework: - - Ivo will get back to the group with specific requirements for the video guides - - Andrès and Adrien will start testing creation of Live USB environments from the Windows 10 platform, Tomas will peer-review if necessary - - Attila will reach out to the author of "opensuse-guide.org" - - Attila will cook up a nice workflow for the group to use, so that all tasks can be taken up, synced up and shared with minimal overhead or duplication - - Adrien will draft a letter / message to the community (to sync up with the other tasks above) to get more help where needed - ------------------------ Things to discuss between now and the next meeting: - - When is next meeting happening? - ------------------------ Things to discuss in the next meeting: 1 Check homework This may take the entire session. Other possible subjects to touch on: 2 Decide which tasks could be done for improving the learning experience in the following departments: - -- Charting new territories: Making an easy-to-look-at, 10'000 feet birdview of the openSUSE community to give new users a taste of the openSUSE community and ecosystem - -- Pre-install guide: Helping users see where their use-case fits in the world of openSUSE distros, and think ahead important in-install choices - -- Installer helper: Structure the info given by identifying clear turning points in the installer to help people understand the consequences (partially overlaps with Pre-install guide obviously) - -- Post-install guide: Best practices, workflows, and post-install tips & tricks 3 Structure workflow around these tasks -----BEGIN PGP SIGNATURE----- iQEzBAEBCgAdFiEEU4ol/0bSQTwqpAkNMy9Aieh+wJwFAl9tpcAACgkQMy9Aieh+ wJy36gf8CEYMQUGy24umdLg+CkzGePUP1i2/wW77WwphUXXTiiApaL55G5+h/AVF G4+3Cnbc0EVbvSd8b01erfYcP4Mqq2mnOOZZHfa2JyMtFaBxKYI9+aw4q3rMcBbE kZRClsvhm/DaV4O7vYoeyJiLY0THj2/W5e3ai0nA+vYqgbdueQITzYJFnkwUbupp cOJLDrXBPbd9kSDC3LGgAou0QKA72hvXpS0GBOePdPxOZGNXorGn9tsaAxoOHOcP 2ijflrV0KlQ0mfGZp0j5fBjIO/FcBydFSs1fB4rk/strbzo8kgq9h7htmYqDmzu2 mhbdZeGD7XRG5892JaYJKpYintKfow== =dA/L -----END PGP SIGNATURE----- -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

1 0

[opensuse-doc] Docs Meeting - Thursday 24 Sep, 1800 UTC
by Lana Brindley 23 Sep '20

23 Sep '20

Hi everyone, A second meeting is now scheduled at a twelve-hour offset from the first, on Thursday 24 Sept at 1800 UTC at https://meet.opensuse.org/opensuse-docs. To make offset meetings like this work without too much of a disconnect between them, I've successfully used a rolling agenda in the past, so let's give it a try. With that in mind, I have seeded the agenda at https://en.opensuse.org/Documentation:Meetings with the same agenda we used last time. Feel free to add items that you want to discuss, which will then be picked up in the next 0600 meeting, next week. I won't be attending the 1800 meeting, as it's at 4am for me, so if someone can take notes and distribute, that would be great. In the meantime, feel free to come along to the Telegram group: https://t.me/opensuse_docs Lana -- Lana Brindley @Loquacities Technical Writer - SUSE Manager "The question is," said Alice, "whether you can make words mean so many different things." -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

2 1

[opensuse-doc] Re: Meeting 1 moving on to 2
by Lana Brindley 23 Sep '20

23 Sep '20

Hi Adrien, Thanks for these notes! Responses inline ... On 17/09/2020 17:46, Adrien Glauser wrote: > Heya folks, > > was nice discussing face to face! Eager for more though, as I think we have barely scratched the surface of what there is to do :) > > About that, I dig Frank's brainstorming idea. Perhaps each of us could write on the wiki page (first meeting, talk section) the main priorities from their opinion? For example, is it refreshing the wiki in particular? Or making key issues from the official doc easier to access and in a form that is more pleasant to newcomers? Or making non-just-textual guides for people interested in openSUSE? Or something else? Yes, I think we can do this on the wiki. I've just put the minutes up from the meeting, with a link to the discussion page: https://en.opensuse.org/Talk:Documentation:Meetings#Brainstorming > > Not I am going to be brutally honest: I know I am much more efficient if meetings try to do one of these things: > > 1) explaining a technical or complex issue that demands quite a bit of attention to details > 2) debating a specific question, i.e. should we do X? > 3) planning something, i.e. who's gonna do X and how? > > In other words I dig meetings that try to address a specific matter, either by zooming in on it or by breaking it down into several closed questions. > > Of course it's just a first meeting, no big deal and no pressure, I think there is a good mindset and I am pretty sure we can make something very good out of it. But it would be delightful if we could try to work stuff a bit ahead of meetings so that we can build on it when we meet :P Absolutely agree, and it's the reason we need to ensure we let people know that meetings are coming up, and to call for agenda items. Another thing I was thinking was that if we're going to have alternating timezone meetings, we will need to ensure the agenda rolls with the meetings: so it's one agenda across two meetings. This will help prevent us from having people in one tz working on one set of things, and people in the other tz working on something different. I'll sort this out when I arrange the upcoming meetings. > > Also I sense there are two perspectives on what we are trying to do: the "insider's" perspective on the doc / wiki / platform ("How to make the best out of the stuff we already have?"). This is a totally valid perspective. You guys have years of experience, while I've been using openSUSE for a couple of months only. > > But there is also another perspective, which is more like the one I was feeling from Attila's and Ivo's messages, which is: "Imagine you're about to install an openSUSE distro for the first time in your life. What can the tech and doc guys from the distro make life easy for you?" > > There will be some point where the two perspectives will meet, obviously. Still they are different paths, with different questions and tools. I really think we should clarify what path people want to go. Practically this means we can organize ourselves in smaller teams (1 for each path) or all prioritize one path over the other temporarily. I don't see these two things as being opposed in any way, we really shouldn't have one without the other. After all, it's no good having a great set of beginner resources without having a platform to host them on. I also think that while this needs to be a community effort primarily, it's super important that we have representation within SUSE, too, because we need to be able to interface with their work, processes, and resources. > > It's just my 2 cents. I am not trying to frame the whole project within my own subjective perspective, just trying to see how we can sync up on this. > > Best and see you soon, > > Adrien > > PS: Mail owner, can you please let this message through? I had to modify it twice to avoid triggering some unknown rule. If this third attempt fails I will need your assistance... I got the message directly, and I'm hoping that replying to the list will send it through. I can't see any way of editing permissions in the mailing list, though, so I'm not sure what rules there might be. I'll see if I can email someone and find out how to administer this list better. Lana -- Lana Brindley @Loquacities Technical Writer - SUSE Manager "The question is," said Alice, "whether you can make words mean so many different things." -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

3 3

[opensuse-doc] Kickoff Meeting
by Lana Brindley 20 Sep '20

20 Sep '20

Hi everyone, After some discussion here and on Telegram, we have scheduled a kickoff meeting for next Thursday 17 Sept at 0600 UTC at https://meet.opensuse.org/opensuse-docs. Please have a think about what you would like to see in the openSUSE docs and add agenda items to the wiki here: https://en.opensuse.org/Documentation:Meetings In the meantime, feel free to come along to our new Telegram group: https://t.me/opensuse_docs Thanks for the great discussion, can't wait to chat more next week! Lana -- Lana Brindley @Loquacities Technical Writer - SUSE Manager "The question is," said Alice, "whether you can make words mean so many different things." -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

2 2

Re: [opensuse-doc] Re: Meeting 1 moving on to 2
by Adrien Glauser 18 Sep '20

18 Sep '20

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Erratum: I meant 1800 UTC as a proposal for the next meeting -----BEGIN PGP SIGNATURE----- iQEzBAEBCgAdFiEEU4ol/0bSQTwqpAkNMy9Aieh+wJwFAl9k4q0ACgkQMy9Aieh+ wJxqvggAujjVFw1rmzqTAGhWa1KCGBaGPEeDkYmlJMbNjQarsmNtY6UsJQn5q37v jrDBZA5bDdzHEa2hhOGPRD9D3OfioPAGYuz7HUwMb52CQRssb2DEVGty3K3AWYeB iBDFsdOkf6Rd57UjphOBqifTF3JZskIUVux9ROFD47b7ar/uJEz3onpyn8cf1nbH EUVTiebe1EvMIy55Jw8aPGpKSIMXbJJkO0EVc54snbTgauMwve7BGFWr6yZIKUo4 u9/avqRj063Y9V1KFswBQOBPG5zp88+9qGFt19vFwUdIAeE/YYtYRFixxrJEsB/D lnYl0tMm2SGYMiBKyrLAEaQkKMU7mg== =b8Ef -----END PGP SIGNATURE----- -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

1 0

Re: [opensuse-doc] Would like to contribute
by Adrien Glauser 10 Sep '20

10 Sep '20

Hello, Sorry for jumping on a running train. I participate in the Telegram group Attila mentioned in his first message below. I too think it would be awesome to get future and current openSUSE's users the best doc available. However before anything else perhaps we should clarify something. As I understand it, Attila's main point in his original message was to lower the entry-barrier for new openSUSE users, not to necessarily have the wiki removed and the doc rewritten. If this is correct, then I think I share his goal, as I think the easily accessible yet outdated wiki might intercept or delay users who actually need to get the docs, while not necessarily creating a very enticing experience. Of course every open source project needs active volunteers, and a wiki makes this clear, But I think that the best way to motivate new users is to first offer them information that is relevant to their issues (and we know what issues new users are most likely to run into), and to present it in an enjoyable way. Which leads me to believe that: 1) a first layer of information catering to new users, anticipating their needs and guiding them to better understand their issues, is very valuable 2) the previous condition cannot be met only with static doc (i.e. a manual or handbook in the sense of docs.opensuse.org), because a manual is not enticing to everybody and does not unwrap information in layers relevantly connected to common issues (being linear and not interactive) 3) the current doc is awesome and I think it can stay the way it is because it still performs an important role (i.e. a basic "source of truth" for users who most need it) Do we all agree on this? If so, and if I am understanding Attila's initiative correctly, we'll need more than punctual, spontaneous amendments to the docs. We need to discuss and coordinate to get contents presented in a more perspicuous way. We need a "contents redesign".. What do you think? Best, Adrien ------------------------------------ Hi Lana, Thank you for your help, much appreciated. The repo you linked to seem to create content for doc.opensuse.org instead of the openSUSE wiki (https://en.opensuse.org/Main_Page) or the wiki is being phased out and things are being moved over to doc.opensuse.org? To be honest I much prefer the format of doc.opensuse.org. Removing the wiki might be a good idea or forwarding it to the docs. Definitely missing content, the opening page would require some tuning and an easier way to find it maybe? Hopefully can assist with the work in the very near future after got the technicalities out of the way. Chances are that I'm going to take you up on your offer and disturb you with my questions ;) Attila ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Wednesday, September 9, 2020 7:40 AM, Lana Brindley <lbrindley@xxxxxxx> wrote: Hi Attila, This is a common refrain! It is possible to contribute directly to the openSUSE documentation, the repo is here: https://github.com/SUSE/doc-sle Personally, I think it is more valuable to contribute to the docs directly, rather than having great content tucked away on an unused wiki, but I also appreciate that contributing directly to a repo like this can be a little daunting if you are not a trained technical writer. With that in mind, I'm absolutely happy to help you out if you have questions :) Lana On 08/09/2020 23:51, adathor wrote: Hi openSUSE-Doc Team, My name is Attila (adathor). We had a fairly long and interesting conversation yesterday on the official Telegram group in regards to the openSUSE wiki and the potential problems around it due to the lack of contributors. Me and probably a few of us from that group would be able to put in some time and help improving the wiki. Checked the Wiki Team page, but considering that it hasn't been updated since 2018 thought it's best to reach out and educate myself about the current status of the Wiki and where is it that you guys would require the most help. Was also thinking a little about how we could help changing up the opening page of the Wiki with guides for - installing openSUSE [$distro] to help first time users - this could also include a YouTube video -, - adding information on tools like Snapper, Opi, transactional-updates, rebootmgr, helth-checker etc. - Distribution overview, that would include the differences compared to other distros and the benefits of using oS, - Clear contribution options and guide, - FAQ - Links to international communities. Any guidance on how to contribute, what are your priorities and the current status of the Wiki would be much appreciated. A. -- Lana Brindley @Loquacities Technical Writer - SUSE Manager "The question is," said Alice, "whether you can make words mean so many different things." -------------------------------------------------------------------------------------------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx To contact the owner, e-mail: opensuse-doc+owner@xxxxxxxxxxxx -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

2 1

[opensuse-doc] Would like to contribute
by adathor 09 Sep '20

09 Sep '20

Hi openSUSE-Doc Team, My name is Attila (adathor). We had a fairly long and interesting conversation yesterday on the official Telegram group in regards to the openSUSE wiki and the potential problems around it due to the lack of contributors. Me and probably a few of us from that group would be able to put in some time and help improving the wiki. Checked the Wiki Team page, but considering that it hasn't been updated since 2018 thought it's best to reach out and educate myself about the current status of the Wiki and where is it that you guys would require the most help. Was also thinking a little about how we could help changing up the opening page of the Wiki with guides for - installing openSUSE [$distro] to help first time users - this could also include a YouTube video -, - adding information on tools like Snapper, Opi, transactional-updates, rebootmgr, helth-checker etc. - Distribution overview, that would include the differences compared to other distros and the benefits of using oS, - Clear contribution options and guide, - FAQ - Links to international communities. Any guidance on how to contribute, what are your priorities and the current status of the Wiki would be much appreciated. A. -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

2 2