- openSUSE Documentation

Meeting reminder: today at 18:00 UTC+2 at...
by Adrien Glauser 20 Oct '21

20 Oct '21

... https://meet.opensuse.org/docs

2 2

Volunteering
by Patrice Yemmene 17 Oct '21

17 Oct '21

Hello, I am interested in volunteering with openSUSE as a Technical Writer, and was wondering if this would be possible. Best regards, Patrice Yemmene

3 3

Minutes 10092021
by Attila Pinter 14 Sep '21

14 Sep '21

Minutes for our last meeting 10th September, 2021. Deadlines: - doc-o-o meeting next week - we have the logo - cleanup the documentation (~2w works) - Adrien has the details - clean up language wise the content - bring uniformity to the docs - intro - goal - body - lists - refernce as much as we go - YaST installer as the refernce doc to follow - how to contribute - add a link to fork the main repo and start promote "easy getting started" - send a plain text doc to the ML, we pick it up and give proper attributions - how to report content Restored docs: - tumbleweed-cli - MicroOS docs docs-ama For context: https://etherpad.opensuse.org/p/docs-ama - Start answering the questions, issues - Put it out on the wiki and share on the ML - Preparation for a video - Planned for next week Friday (17th Sept.) - announce on project@ that we do this - second round of QnA with interaction - reword the migration to a better synonym videos WIP - lack of time -- Br, A.

1 0

Docs team regular meeting 03-09-2021
by Attila Pinter 02 Sep '21

02 Sep '21

Hi, A reminder, we will have a meeting tomorrow September 3rd, 2021 at 4pm UTC at https://meet.opensuse.org/docs. On the agenda we have the deadlines to discuss and set for ourselves, Adrien will lead the charge on that. This is in a different time than usual, see you there ;) -- Br, A.

1 0

docs meeting minutes 23-08-21
by Attila Pinter 23 Aug '21

23 Aug '21

Please find the minutes below. ## Docs general - Docs team to move forward as community driven docs and move away from positioning ourselves as "official". This will mitigate problems we introduce to developers, maintainers which has been a long discussion along with potential legal issues. - Docs team (who wants to ) help out updating the wiki with relevant docs where we can and needed - Hoping for a bidirectional contribution - Cross-referencing from docs to wikis, keep a list of the pages we help out with - Knurpht: Git{hub,lab} considered as complex and not for docs in general - Adrien: we need to further lower the barrier of entry - Mailing list to be a channel for reviewing and sending in docs in plain text format for those who doesn't know git or want to learn it - Migrate to code-o-o to stay on the openSUSE infra - Mirror the code-o-o repo with the github repo - Adrien: Issue reporting should be linked section by section - Design to be brought closer to the openSUSE's theme - We will need more maintainers and reviewers, we must pursue this avenue further ## Video - Doug said that we could put up videos on the openSUSE YT channel, need to discuss further - Attila: start making video tutorials on week 34 -- Br, A. Sent with [ProtonMail](https://protonmail.com/) Secure Email.

1 0

Doc meeting Aug 20 2021
by Attila Pinter 19 Aug '21

19 Aug '21

Hi all, Our next meeting will be held on August 20, 2021 UTC 6pm at https://meet.opensuse.org/docs and we will continue the conversation of how we move forward (mainly). The meeting minutes from the previous meeting can be found here: https://lists.opensuse.org/archives/list/doc@lists.opensuse.org/thread/TVNG… See you there! -- Br, A.

1 0

Meeting minutes 13-08-21
by Attila Pinter 16 Aug '21

16 Aug '21

Below are the minutes from the August 13th docs meeting: --- Present: Adrien, Andi, Attila, Bill, Ethan, Knurpht, Stefan, Syds ## Video - Project handled by _Ethan_ and _Attila_, but more than open for suggestions and inputs - Maintenance concern for videos >> Focusing on short clips could try and mitigate this issue (somewhat) as recapturing a 2-5min long video is much faster than editing it over and over after an update - Talk with Doug if maybe these tutorial videos are suitable for the openSUSE YouTube channel - _Adrien_: Keep the right distance from the docs, not too far, not too close as it could get confusing for users if something is written and not mentioned in the video or mentioned in the video, but not documented yet, - Pick the focus of docs and videos which is already in progress here: https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/12 - Video format shouldn't be anything complex to keep it maintainable, but have a single cover picture with the agenda and when reaches a milestone - if any - within the video use it to mark what are we talking about in the following block. For example performing a system upgrade with CLI tools and YaST. ## Project ML, community and communications problems - put the "negotiations" and "deprecation" parts of the plan at https://en.opensuse.org/openSUSE:Documentation_migration on hold - carry on with the "flagging" part of the plan only by working hand in hand with wiki maintainers to build presence in a non-destructive fashion, limiting edits to only the clearest of flag opportunities as per https://en.opensuse.org/openSUSE:Documentation_migration - use a polite style and tone especially for external communication - work hand in hand with docs-o-o maintainers to carry on with deploying there as per the intent expressed in minutes shared via the documentation mailing list, but not push this until pending issues are sorted such as "supported-unsupported" use case documentations - brainstorm on criterion for including/excluding software topics to/from the revamped docs (so-called "official vs. unofficial" definition) - Make the documentation efforts and goals more visible ## In regards to supported-unsupported cases we discussed the following options: - Separate supported and unsupported cases from the current docs - Stefan Knorr: Make a clear disclaimer at pages that are not supported by developers - _Attila_: It has been brought to my attention that this might have legal problems still, need to look into it further and clarify - Potentially put unsupported docs under their own category? - Remove controversial contents from the documentations: not delete it, but hide it on the rendered page until they get sorted and there is a decision made. - Some of the conversations is available here: https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/27 ## Assigned tasks: a. with regards to supported-unsupported, the participants will prepare arguments for their position, so that we can vote on a definitive solution in the next meeting. ## To follow up on: - the idea has been aired to build presence using portals instead of flagging individual pages when doing the latter might appear as targeting or attacking the work of maintainers - the idea has been aired to draw attention, when communicating externally, to the fact that we appreciate live conversations, especially for initiating new collaborative processes. - Automatically propose multiple ways to get in touch with us on Telegram, Matrix, ML or live calls ## Meetings: - bi weekly meetings are restarted - Next meeting will be held early on August 20th from 6pm UTC to make a decision on how we go forward from here. -- Br, A. Sent with ProtonMail Secure Email.

1 0

Minutes of the joint meeting with SUSE doc team
by Adrien Glauser 13 Aug '21

13 Aug '21

Dear all, Please find below the minutes of our recent meeting with SUSE documentation team (https://doc.opensuse.org) These minutes are shared as an agreed-upon version resulting from our combined efforts. Thank you to everyone in the SUSE doc team and to Stefan for working out these minutes with us, See you soon, Adrien PS: There is 'news docs' meeting scheduled for 6pm UTC on http://meet.opensuse.org/docs 8<------------------------- Combined version of minutes *************************** Meeting minutes, Wednesday, August 11 Adrien Glauser (openSUSE community), Stefan Knorr (SUSE doc team), Attila Pinter (openSUSE community), Tanja Roth (SUSE doc team) and Frank Sundermeyer (SUSE doc team) AI = action item Topics with agreements: present openSUSE Revamped docs similarly to existing Leap guides on doc.opensuse.org homepage openSUSE Revamped docs primarily describe a product version that is not present on doc.o.o so far: docs for Tumbleweed -> there is no conflict in terms of content openSUSE Revamped docs further focus the use cases of new desktop users on Tumbleweed ideally, specific use cases of new docs should be communicated properly on doc.o.o navigational pages AI openSUSE Revamped team: write descriptions to use on doc.o.o openSUSE Revamped docs are currently generated manually via MkDocs, then pushed to special branch of the source repo SUSE doc team can pick up generated results from there and sync onward to doc.o.o AI SUSE doc team: enable sync process to doc.o.o via cron job (weekly or more often) coordinate in terms of design AI openSUSE Revamped team: talk to openSUSE community designers (@hellcp and @guoyunhe) about branding of the new docs versus the navigation of the page AI SUSE doc team: get a coordinated design for the Leap docs licensing: openSUSE Revamped docs/Leap docs/wiki all use GFDL, enabling re-use open question about whether contributors need to be attributed with their full name for openSUSE Revamped docs not discussed yet: GFDL 1.2 versus GFDL 1.3 AI SUSE doc team: forward Adrien's question on how to attribute individual contributors to SUSE Legal Further topics discussed: ML thread on opensuse-project did not result in consensus on new strategy, openSUSE Revamped team will find way to communicate with wiki documentation authors and build consensus, especially before any destructive actions lunrjs integrated into MkDocs provides full-text search for openSUSE Revamped docs desire to see full-text search for entirety of doc.o.o Adrien/Stefan to look at expanding search to cover more parts of doc.o.o later, if feasible/scalable enabling user feedback for openSUSE Revamped docs: proposal: use three buttons (Edit Source -> opens GH PR, Open Bug -> b.o.o or GH Issue) (Frank) alternatively: wholesale move to code.o.o would allow one main way of providing feedback that also integrates with openSUSE account infra (Stefan) Topics not discussed: timeline of changes to doc.o.o next meeting GFDL 1.2 (wiki, openSUSE Revamped), GFDL 1.3 (SLE docs)

1 0

Upcoming Meeting 13-08-21
by Attila Pinter 12 Aug '21

12 Aug '21

Hi, Just a heads up, we will have a meeting tomorrow August 13, 2021 at 6pm UTC on https://meet.opensuse.org/docs where we will have the following topics on our agenda: - Wiki migration and communications - Issue #27 (https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/27) - Video project -- Br, A. Sent with ProtonMail Secure Email.

1 0

Meeting minutes 16 of April...
by Adrien Glauser 16 Apr '21

16 Apr '21

... can be read at https://en.opensuse.org/Opensuse-docs/minutes-meeting-04-16. Thanks to everyone and see you soon!

1 0

1st Milestone Cleared
by Adrien Glauser 05 Mar '21

05 Mar '21

Dear friends of the docs, Earlier tonight we met to celebrate the achieving of the first milestone, which consisted in promoting the first 4 sections of the docs' table of contents (https://github.com/openSUSE/openSUSE-docs-revamped/blob/dev/ToC.md) to the 'decent beta version' rank. I would like to thank from the bottom of my heart all our relentless contributors: - syds-git (microos) - badarotti (readme and introduction) - apinter (installer) - daviddyess (proof reading) - Ethanol6 (proof reading) - camckay6 (GPU drivers) - Idesmi (proof reading) - surprized (GPU drivers) - Loquacity (proof reading) - gonyere (proof reading) - buxel (proof reading) I'd also would like to extend my gratitude to Sasi for helping us with the future website theme, and last but not least, to Attila for being an incredibly reliable and resilient partner in crime since the beginning of this project. Now we don't forget that there's still a lot to accomplish to meet the next deadline (around May), which consists in the 'spinal cord' of the docs -- sections 7-10 included on Yast, zypper, snapper, and package management, for which there is material aplenty, albeit scattered over our platforms and more importantly, not very attuned to the needs of Tumbleweed users. As you can infer from the list of contributors above, we still need to balance our ratio of excellent proof readers with excellent tech writers. That'll be the topic of my email to the mailing lists next week, where I'll be heading to try to get more contributors. Thanks again and have a beautiful week-end, Adrien

1 0

Meeting 2021-03-05
by Attila Pinter 05 Mar '21

05 Mar '21

We're having a meeting today at 19:00 UTC. https://meet.opensuse.org/opensuse-docs Sent from ProtonMail mobile

1 0

Help us port wiki materials to the upcoming docs!
by Adrien Glauser 25 Jan '21

25 Jan '21

Dear friends of the documentation, There is something very simple which YOU can do from time to time when you have a couple of minutes to fill; it would immensely help us and do good to future users... And the best part is that you start NOW. Everything is explained here: https://etherpad.opensuse.org/p/wiki-pages-reporting Thanks, Yours truly, Adrien

1 0

Upcoming meeting
by Attila Pinter 21 Jan '21

21 Jan '21

Team, We will have our next meeting this week Friday - 22/01/20 - on the usual channel (https://meet.opensuse.org/opensuse-docs) Focus is on the milestones we're hoping to achieve in the near future. Hope you can make it, especially if you're a contributor on GitHub. -- Br, A.

1 0

Last Minutes...
by Adrien Glauser 06 Jan '21

06 Jan '21

...can be found here: https://en.opensuse.org/Opensuse-docs/minutes-meeting-01-06 Best, Adrien

1 0

Last Minutes
by Adrien Glauser 21 Dec '20

21 Dec '20

Dear all, As our activities shifted toward the GitHub repository, where most of the discussions are being held, you won't be surprised to find these minutes quite lean: https://en.opensuse.org/Opensuse-docs/minutes-meeting-12-18 The last few days were quite successful in terms of recruitment; yet we look forward to more contributors ;P Best wishes for the end of the year and see you soon, Adrien

1 0

Meeting Friday 18th of December?
by Adrien Glauser 17 Dec '20

17 Dec '20

Just probing your energy and availability. I can think of a couple of things to discuss: - PRs (I am all in favor of Badr's idea, found in the minutes, to now move to a page-centric workflow, and also we clarify a detail or two about external PRs) - improving the "how to contribute" guidelines with Badr's document, also found in the minutes - clarify a couple of things about the pending issues, PR and the rest The reason I am suggesting this week is that Christmas is drawing closer and not just Christians like to take a few days off in that occasion, and it's going to make planning meetings a little bit more difficult. Let me know! Best, Adrien

3 2

Meeting minutes 11-12-2020
by Attila Pinter 12 Dec '20

12 Dec '20

Present: Ivo, Andres, Mike, Badr, Attila What we discussed: ================== - Licensing On Telegram we discussed the option of using CC BY-SA 4.0, but that brings in a few issues: - compatibility with GPL (https://creativecommons.org/share-your-work/licensing-considerations/compat…) - and a smooth transitioning from the previous docs. We agreed to use the same Licensing the previous team was utilizing: GPL 1.2/1.3. Based on Adrien's points: ========================= - Labeled external branches. ============================ >As hinted at in the my last commit to the README, I suggest we >adopt a workflow where all PRs are made from new branches >labeled appropriately, as suggested in the "three types of >commits" bullet point on the README. If you have a better way of >labeling let me know, it's just a suggestion to improve the >readability of the git history (I will have to squash my own >commits too so not giving lessons here)." We agreed to this. Furthermore: - We probably need to agree on commit message structure as commit messages have to be descriptive. - Each branch should be one document, each PR should be for that single document. Badr already started to work on a cheatsheet/guide for git already where we could include the workflow too: https://badarotti.github.io/openSUSE-docs-revamped/contributing/ - Adjusting presentation: ========================== >I am still trying to figure out a good model for presenting >documentation differently depending on the audience, TW vs Leap, >"give me the list of steps" vs "explain more", as described >here: https://github.com/openSUSE/openSUSE-docs->revamped/issues/11#issuecomment-739492149. For me it's the main >blocker as of now, in the sense that it's preventing me from >diving into writing this or that article I had ideas for. If you >could make progress on this that would be huge. A linked >question is whether we should use versioning for this, somehow. Seems that Badr done the heavy lifting for us already (special thanks for this awesome work): https://badarotti.github.io/openSUSE-docs-revamped/distribution/ The strucutre covers both Leap and TW as the installation is not that different from each other. The install section is more a step-by-step guide Section 1-2 - "Pre-install" and "Install"- is to get you up and running ASAP. "After install Setup" and "Advanced topics": deep dive, advanced docs << "Explain more" sections Recommended setups: config based on a user profiles, generic recommendations as per the user requirements. "Advanced topics": more details can be added here on oS infra and software. Main focus on Leap and TW as needed. Versioning to follow the exact versioning of Leap and TW should have no versioning. When there is a Leap version bump we branch it and change the version number. For reference how versioning for different releases could look like: https://www.ixsystems.com/documentation/freenas/11.3-U5/freenas.html Also Badr suggested a different approach to PRs: everybody adopt a page, works on it and discuss under the issues the changes and make a PR if agreed on and applied discussed changes if any. We should consider this at least during the early stages of the project, TBD. - Versioning: ============== Speaking of versioning, added `mkdocs versioning` at https://github.com/openSUSE/openSUSE-docs-revamped/tree/web-functions-versi…. Careful this one is both a python module of its own and an mkdocs plugin. Needs *installing* before building. The plugin option has been accepted. - Rolling vs. stable description: ================================== https://badarotti.github.io/openSUSE-docs-revamped/distribution/ Must read the way Badr explains the difference between Leap and TW - stable vs. rolling - and we need to have a discussion on this. -- Br, A.

2 2

Meeting 20201210
by Attila Pinter 11 Dec '20

11 Dec '20

Dear All, The next meeting is tomorrow - 10 December 2020 - at 18.15UTC. https://meet.opensuse.org/opensuse-docs The main agenda are issues currently open on Github (https://github.com/openSUSE/openSUSE-docs-revamped) See you there. -- Br, A.

3 2

[opensuse-doc] Nov 27: Minutes
by Adrien Glauser 27 Nov '20

27 Nov '20

Hello, Please find the minutes at https://en.opensuse.org/Opensuse-docs/minutes-meeting-11-27. Thanks to everyone who participated to this and the previous meetings! Have a pleasant week-end, Adrien

1 0

[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