- openSUSE Documentation

[opensuse-doc] Meeting notice: Friday, Nov 27 at 6:30 pm UTC
by Adrien Glauser 24 Nov '20

24 Nov '20

Hello everyone, We're meeting this Friday, Nov 27 at 6:30 pm UTC to discuss and plan the first milestones of our work toward an improved openSUSE docs. Main topics will be: 1) contents priorities (documenting in view of the installation process vs the rest) 2) layering contents according to different audience 3) workflow with https://github.com/Nycticorax/openSUSE-docs-revamped The bigger picture, which won't be addressed in this meeting but might be useful to bear in mind: https://docs.google.com/document/d/ 1zERjqqQrWBAoM3B25BIQ4hvTFU_Y7S8L57bh-wb6ld4/ See you there! Adrien

1 0

[opensuse-doc] Meeting minutes 21-11-2020
by Attila Pinter 20 Nov '20

20 Nov '20

Was a great night for docs! Special thanks to Adrien for the heavy lifting and easing the decision making process with his research! Meeting minutes: ========================= Present: Ivo, Adrien, Attila What we discussed: ================== - Documentation platform: Based on Adrien's work and research - which is available here if you missed it: https://en.opensuse.org/Opensuse-docs/prep-meeting-11-20 - we've been able to settle on the documentation platform which will be: MkDocs. We reached this decision by following our previously set guidelines - can find it in Adrien's research - while keeping a low barrier of entry for contributors with a short learning curve. - Video team Past few days the Video team gained full access to their KVM server to start recording videos. Ivo will try and round up volunteers for the video team and reach out to communities for help with content creation and translation. Next steps to follow. ================== If you're interested in helping out with the openSUSE documentation or video content creation don't be shy and hit us up ;) -- Br, A.

1 0

[opensuse-doc] Next meeting 20112020
by Attila Pinter 20 Nov '20

20 Nov '20

Dear All, The next meeting will be held this week Friday (20 November, 2020) at 1800UTC at https://meet.opensuse.org/opensuse-docs. https://en.opensuse.org/Documentation:Meetings#Meeting_.236_.7C_20_November…. Do prepare for a discussion around the documentation platform. -- Br, A.

2 2

[opensuse-doc] opensuse-docs team sync message 20201117
by Attila Pinter 16 Nov '20

16 Nov '20

Dear All, This is just a quick update mail of the recent happenings. We were finally able to work out the network issues and get a KVM server running for the Video Team - Ivo -. The Video Team is still looking for volunteers who can help with creating the tutorial videos. Ivo is looking for the following: - a native English speaker for recording the audio for the content, - someone who is interested in learning the recording process from Ivo and help him with the recordings. With the network issues out of the way next is setting up the ELK for analyzing different openSUSE channels for common problems and setting our priorities right. -- Br, A.

1 0

[opensuse-doc] This ML has been migrated
by Lana Brindley 11 Nov '20

11 Nov '20

Hi everyone, You should have all received an email, but this is just confirming that our ML has been migrated, and the email address for this list has now changed (although apparently the old ones will continue working for now). Old email address: opensuse-doc(a)opensuse.org New email address: doc(a)lists.opensuse.org You will need to update your address book, and probably any filters. For details on the header changes, check https://en.opensuse.org/openSUSE:Mailing_Lists_Migration Lana -- Lana Brindley @Loquacities Technical Writer - SUSE Manager "The question is," said Alice, "whether you can make words mean so many different things."

1 0

[opensuse-doc] Meeting minutes 20201107
by Attila Pinter 06 Nov '20

06 Nov '20

Thank you all for your time and contribution! ========================= Present: Ivo, Tomas, Adrian, Quang, Attila What we discussed: ================== - Next steps on settling on a static page generator for docs We have the following list available for us to pick a solution from contributed by members of the doc team: - AsciiDoc/Adoc - Github Pages - Read the docs - MkDocs - Gitbook - Gatsby - VuePress - Docusaurus - Antora (uses Asciidoc/Adoc) - Dauxio - Sphinx - mdBook - BookStack - Doxgen - Hugo & Docsy We're aiming to settle on a decision within the next 1-2 weeks. If you're interested in participating in the decision making do sound your opinion and share your reasons for your preferred platform. Once we settle on this we can continue settling on a format and workflow utilized across the docs team. Just to clarify! If you're not comfortable to participate with your docs in any of the above listed option and/or you prefer to use something else and maintain your docs elsewhere, but would like your docs to make it to the unified platform just leave a link to your docs and we will include them with the source included. - Video team discussion: Ivo to establish a unique standard that would aid in differentiating/identifying our video contents. Simple, short, to-the-point materials. Ivo also offered to record our meetings for those who can't make it in a video/audio format. If you interested in listening/wathing us talking docs let us know here/Telegram/Matrix/Discord. ===================== Clarification points: ===================== - We're planning to set up an ELK instance to be able to collect issues across multiple channels of openSUSE such as Discord, Reddit, Telegram, basically the user focused channels. The purpose of the initiative is to have a better insight into reoccurring issues so we can prioritize our work and also to measure the success of the docs team. - The meetings are currently happening every two weeks at 1800UTC on Fridays. We can set meetings for 0600UTC again if needed/there is demand for it. - The "team sync mails" are happening weekly. If you don't see a mail on a given week that is because nothing happened/changed. -- Br, A. -- 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] Next meeting 2020-11-06
by Attila Pinter 05 Nov '20

05 Nov '20

Dear All, Apologies for the super late update - second week on the job and already slipping - we have a meeting on November 6, Friday 1800 UTC. The details will be available here: https://en.opensuse.org/Documentation:Meetings Jitsi link: https://meet.opensuse.org/opensuse-docs Also there has been no "sync mail" as there is nothing really changed from last week. -- Br, A. -- 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] opensuse-docs team sync message 20201027
by Attila Pinter 27 Oct '20

27 Oct '20

This is a sync message collecting key information from the Telegram group (bridged to #docs:opensuse.org and #docs at discord.gg/opensuse) and Trello. These "sync" messages are intended to keep everyone in the Docs team informed utilizing the mailing list. The "sync" messages are going to be sent on a weekly basis or if something is important will be shared pretty much immediately. If you have something to add please feel free to do so here and will be added by me on Trello for example. ========================================================================= ========================================================================= What we've been discussing on Telegram and Trello since the last meeting: - Planning the next meeting Badr said: "I propose another 2 or 3 consecutive meeting since we have a lot to discuss. For example the website, we need to discuss my proposal and any other proposals out there. I've also added some options to discuss regarding the documentation platforms in a Trello list. etc." Adrian said: " I am all for having more meetings but I also hear those who want to start being productive. How about this: - we meet the upcoming week Thursday or Friday - we carve up our live time so that every subgroup/role (collecting support data, doc contents & platform, videos) have their fare share, perhaps 10-15 min max. - the rest of the time is for new tasks or "meta" things (i.e. adjusting how we work)" Attila said: "Maybe in the meanwhile we could get a few things rolling on Trello for instance - which I'm going to sync tomorrow to the ML -. Like populating the "Reference documentation" list which already has some really great topics/tasks listed. Would be also nice to settle internally on the platform we going to use." Infrastructure related: ======================= - Looking into acessing either the Elastic deployment on the openSUSE infrastructure (if exists) or deploying our own by myself for analysing the main openSUSE communication channels. This would aid our effort greatly in terms of prioritizing issues. If I deploy ELK acess will be provider to the Docs/Web/Heroes team as well. - Moving Trello to a Kanban deployed on openSUSE infrastructure. Maybe we can help out with this the Web/Heroes team. https://en.opensuse.org/Help:Kanban - We're looking for a documentation platform to be utilized for publishing documentations. Currently we have the following solutions on our list (do feel free and raise your opinion): - Github pages - Read the Docs - MkDocs - Gitbook.com - Gatsby - VuePress - Docusaurus - Antora - en.opensuse.org (current wiki) - Adoc (it uses asciidoc and antora and used for SUSE Manager docs as well, upstream doc: https://www.uyuni-project.org/uyuni-docs/uyuni/index.html Toolchain: https://github.com/uyuni-project/uyuni-docs. Lana said: "interestingly, since we moved the suse manager docs from docbook to adoc, we've also had a huge uptick in external contributors, too") Actual documentation work ========================= - Reference documentation list population. Currently has the following items and looking to add more: - Comparison chart for supported desktop environments? - Guide similar to GNOME guide for all supported desktops - Tumbleweed snapshots workflow vs. Tumbleweed packages workflow - Teams: You can find more here: https://en.opensuse.org/Opensuse-docs/prep-meeting-10-23#Roles Still looking for volunteers fo the Video team, Collectors of Most Pressing Issues and writers of course. If interested feel free to reach out! As a refresher from the last meeting: > "2) Continuity >Job => Make sure no one is left behind, takes minutes in meetings and tries to >keep the mailing list people in the loop, keep tabs on who does what, etc. > >3) Pressing Issues >Job => Mobilize search & data aggregation tools (oS Heroes may grant access to >Elastic Search). Consolidate data about the pressing issues. > >Attila volunteers for 2 and 3. > >4) Videos >- Ivo, Emmanuel >- They will work on a script they will share on the wiki. >Topics: >1) explain the differences between the distros & differences with Debian-based >distros >2) Yast & openSUSE specifics, especially YaST >3) Plasma "tips & tricks": power-user workflows, widgets, tiling features, >exposé-like features, mult-desktops / multi-monitors >They will get in touch with the marketing department, seeking for help and >syncing up for *promotional* contents. >They will share their exact needs. -- Br, A. -- 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] Meeting minutes of openSUSE-doc meeting 20201023
by Attila Pinter 23 Oct '20

23 Oct '20

Thank you all for joining the meeting! As a side note: in future meetings please avoid going so hard off-topic ;) -- Br, A. Minutes 23rd of October 2020 ============================ 3 rules of communication ------------------------ Agreed that: - everyone use their favorite channel of communication - every decision made are first shared to MLs & then stored on the Wiki at some point. Some reasonable delay should be tolerated. - MLs will be used on a regular basis to keep contributors & others in the loop. Ivo's proposal to add to the documentation ------------------------------------------ Need to add clear guidelines catering to professional or more generally *conservative* users -- typically corporate -- to keep their workflow afloat pre- , during and after *migrating* from SLES to Leap. Need to chart the most useful repositories for professional users. Groups ------ 1) Docs proper Every section of the docs has 1 maintainer; everyone can move throughout sections freely. - Mike - Attila - Baldr - Adrien Need to make explicit how we approve and peer-review every step along the way. Need to decide for a platform -- static doc generators seem to fit the bill. Need to have to make sure who takes responsibility of the 3 sections (before, during, after). 2) Continuity Job => Make sure no one is left behind, takes minutes in meetings and tries to keep the mailing list people in the loop, keep tabs on who does what, etc. 3) Pressing Issues Job => Mobilize search & data aggregation tools (oS Heroes may grant access to Elastic Search). Consolidate data about the pressing issues. Attila volunteers for 2 and 3. 4) Videos - Ivo, Emmanuel - They will work on a script they will share on the wiki. Topics: 1) explain the differences between the distros & differences with Debian-based distros 2) Yast & openSUSE specifics, especially YaST 3) Plasma "tips & tricks": power-user workflows, widgets, tiling features, exposé-like features, mult-desktops / multi-monitors They will get in touch with the marketing department, seeking for help and syncing up for *promotional* contents. They will share their exact needs. -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

1 0

[Fwd: Re: [opensuse-doc] Upcoming meeting]]
by TomasK 23 Oct '20

23 Oct '20

On Fri, 2020-10-23 at 11:23 +0200, Adrien Glauser wrote: > > > I am using these things to strike a balance between the pain of > > > turning very circumstantial texts into media wiki syntax and the > > > pain for others to have to jump between too many tools. So far > > > we've been able to work with just trello, google docs, the > > > opensuse wiki, telegram and emails -- not too bad don't you > > > think? :) . > > > > There is no need to get defensive. > > > > I am using these things to strike a balance between the pain of > > > > turning very circumstantial texts into media wiki syntax and > > > > the pain for others to have to jump between too many tools. So > > > > far we've been able to work with just trello, google docs, the > > > > opensuse wiki, telegram and emails -- not too bad don't you > > > > think? :) . > > > > > > There is no need to get defensive. local = opensuse.org > > I specifically refer to opensuse documentation on this link: > > https://docs.google.com/document/d/1zERjqqQrWBAoM3B25BIQ4hvTFU_Y7S8 > > L57b > > h-wb6ld4/edit?usp=sharing > > Followed by bunch of third party resources listed in your telegram > > post. > > > > These "third party resources" are websites, which don't do much > except > serve HTTP requests. I mentioned them so that we can visit them, look > around, a more forward with some baseline of an idea. Nothing else. > Pure references. > > My understanding is that you want all of us to abide by a principle > that says that there is moral requirement not to use non-FOSS > software > when there is a FOSS alternative. But I fail to understand how this > principle applies to websites in general, or to the use of them as I > was suggesting. If you meant this principle to rule out not websites > but Telegram, I don't know what to say except: > 1) that I am trying to make everything to not create a gap between > users and non-users, as you can witness from my activity on the MLs; > 2) that the entire openSUSE community is present on many of these > non- > FOSS platforms, such as Discord and Telegram (if we mean "non-FOSS" > to > cover server code and not just client code). > > On the other hand, I am trying to acknowledge the fact that you don't > feel at ease with these websites, and my assumption was that this was > the case because you felt like the normative principle stated above > made them morally wrong to use / browse. > > I think you are mistaken in you application of the moral principle (I > mean, does Richard Stallman buys his airplane tickets from Emacs?), > but > I am ready to suspend judgment and to make a step in your direction. > Hence my suggestion that you clarify which tools you think are > permitted as per your understanding of the moral principle. > > I hope this is crystal clear now. > How is all this relevant to opensuse documentation and website improvements? This is a statement with question mark - no answer or explanation needed - I have no interest in digressing from the and discussing politics I interpret your long email as - we work though the social media and do not intend to change for now. Fair enough - I will find different place/way to help. Tomas -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org

1 0