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