- openSUSE Documentation

[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

[opensuse-doc] Any help needed with documentation for the upcoming openSuSE 15.2 release?
by tomas.kuchta.lists＠gmail.com 01 Mar '20

01 Mar '20

Hi, I was browsing openSuSE.org news couple of weeks ago - someone mentioned documentation as priority/deficiency for the project - Maybe, I COULD HELP. I would be happy to help with anything what is needed for/by the community regardless of my personal bias. Quick Introduction: ------------------- I am using and administering SLE, openSuSE for years, since v. 6.x/7.0. I used to run small data center professionally for about 10 years, mainly SES/SLED hosting engineering big data analytic and bunch of (<100) interactive enginners/CAD users. I am: * KDE user at home, GNOME at work * use ansible to configure hosts * use NextCloud/OwnCloud - as a replacement for personal data sinks in Anrdoid * practical, minimalist when it comes to DEs - I do not "enjoy" configuring things I cannot automate+deploy - any DEs, web-browsers, email clients. My interests are in distributed computing - these days it is called cloud native infrastructure/application, engineering data collection, parsing and analysis. I can consistently give 5+ hours a week, more when/as needed. Communication - currently living in EST time zone, home is in PST. To meet in person, I attend LFNW every year, some years SCALE. This year maybe different - depending on covid-19. Please let me know if I can help? Tomas -- 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: [opensuse-project] doc.opensuse.org
by Lana Brindley 15 Oct '19

15 Oct '19

(Adding the opensuse docs ML to cc) On 15/10/2019 22:46, Jason Evans wrote: >> if we're building up on the existing documentation contributed by >> SUSE >> folks. > Actually I'm talking about creating new documents and not just putting > in pull requests for the existing docs. For example, besides the quick > start guide that I wrote last spring there isn't much for Kubic. I > think we need a new document build from scratch on how to use it. The repo is open, so if you think a new document is required, then go right ahead. >> I've been looking at Docbook the past few days in order to contribute >> somehow on Container documentation. I think Docbook's fine, >> especially >> >> >> Having part of the documentation written in Docbook and another part >> in >> AsciiDoc leads to the same as having doc.o.o vs wiki.o.o. > Actually the SUSE docs team does that now. Daps natively handles both. > Some people only write in Docbook and some only write in asciidoc. You > can't tell the difference because Daps produces the same output for > both. That is true. If you're editing existing docbook content, then use docbook. Of course, if you want to create a new document, feel free to use asciidoc. The use of asciidoc is still fairly new within the team, so there are fewer guidelines, etc, written down, but that is improving. I have used both languages extensively, so I'm always here to help if you have questions on syntax or usage. > > I think the goal would be to encourage community participation. Docbook > creates an artificial roadblock to that because of it's significantly > higher learning curve. We should want people spending their valuable > time submitting pull requests to help build something not spending > hours trying to find out why their xml isn't working. I agree with you on this. I've worked on a few community docs teams that switched from heavier languages like docbook to markup languages, and there's always a corresponding increase in outside contributions after the change. Thanks for your interest :) 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

1 0

[opensuse-doc] Re: [opensuse-project] openSUSE documentation
by Lana Brindley 11 Oct '19

11 Oct '19

On 07/10/2019 06:43, Mike McCallister wrote: > Ish, > > Back in March, Lana Brindley offered to work on revising/updating the openSUSE docs (https://lists.opensuse.org/opensuse-project/2019-03/msg00033.html) I also offered to help at that time. She ran into some issues opening communication with the SUSE Docs Team. I don't know where that initiative stands right now, but it's good to know there are others who want to help with openSUSE docs. > Yes, I'm still here, and still interested in getting a group together to work on openSUSE docs. As Frank pointed out, the best place to do that is the doc-sle repo: https://github.com/SUSE/doc-sle While I think it would be ideal to have the opensuse docs in their own repo, it's not technically feasible at this stage. I would definitely advocate for contributing to the docs in the repo rather than the wiki, though, just to avoid silos. The whole point of open source is to give back, and we can't do that if we're contributing in our own sandbox. Happy to help anyone who might like some pointers on using github or docbook. Also, the docs mailing list has been reactivated, so feel free to chat further there (it's in cc). Lana > Another thread on this is on the opensuse-web list. I can't find that link, but it's around the same time. > > Mike McCallister > > On 10/6/2019 5:47 AM, Ish Sookun wrote: >> Folks, >> >> During the openSUSE Asia Summit's community meeting we discussed things >> that should be & can be done. One of those was about the openSUSE >> documentation. >> >> I checked doc.opensuse.org. >> >> I notice that all the documentation are currently copyrighted [1] by >> SUSE. Although the docs are granted GNU Free Documentation License it >> sounds proper to have the content ownership under openSUSE. Such a thing >> should not wait for the creation of a foundation. >> >> It also appears that the documentation workload is currently on the >> shoulders of the SUSE documentation team (only). I would like to help, >> more specifically collaborating with Kubic/MicroOS team to have a >> Container documentation. How should I proceed? >> >> Regards, >> >> Ish Sookun >> >> [1] >> https://doc.opensuse.org/documentation/leap/virtualization/book.virt_color_… -- 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 6

[opensuse-doc] Greetings
by Robin Shepheard 09 Oct '19

09 Oct '19

Hi everyone Just a wish intro. I am looking at helping with documentation for the project if I can. I have been using Linux since the late 90's and used many different flavours for various purposes over the years. I haven't had much chance to contribute during that time but due to my work commitments I shall have more time to do so. I will just be a lurker for a little while as I will need to familiarise myself with docbook and github but hope to be able to help contributing soon. As this is my first venture in a project like this any pointers would be very gratefully received although I am happy to figure stuff out by myself where I can. Oh and if it makes any difference to anyone, I live in the south or the UK and work 4 on 4 off nightshifts so will be around at all sorts of random times Cheers Robin Sent with ProtonMail Secure Email.

2 3