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.
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.
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.
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.
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)
