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/compati...) - 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-versio.... 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.
Just a polite note - I was incommunicado and skipped a few meetings. I did not abandon this effort - I am simply in the middle of changing jobs and moving across the country. So, many severe distractions were popping up at me left and right. I hope to converge towards some form of normality after the new year. Best, Tomas On Fri, 2020-12-11 at 20:18 +0000, Attila Pinter wrote:
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/compatible-licenses) - 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-rev amped/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-versioning. 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. _______________________________________________ openSUSE Documentation mailing list -- doc@lists.opensuse.org To unsubscribe, email doc-leave@lists.opensuse.org List Netiquette: https://en.opensuse.org/openSUSE:Mailing_list_netiqu ette List Archives: https://lists.opensuse.org/archives/list/doc@lists.ope nsuse.org
Hi Tomas, Glad to hear from you. Congrats on the new job and looking forward to have you back in the new year ;) Br, A. -------- Original Message -------- On Dec 12, 2020, 3:29 AM, TomasK wrote:
Just a polite note - I was incommunicado and skipped a few meetings.
I did not abandon this effort - I am simply in the middle of changing jobs and moving across the country.
So, many severe distractions were popping up at me left and right. I hope to converge towards some form of normality after the new year.
Best, Tomas
On Fri, 2020-12-11 at 20:18 +0000, Attila Pinter wrote:
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/compatible-licenses) - 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-rev amped/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-versioning. 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. _______________________________________________ openSUSE Documentation mailing list -- doc@lists.opensuse.org To unsubscribe, email doc-leave@lists.opensuse.org List Netiquette: https://en.opensuse.org/openSUSE:Mailing_list_netiqu ette List Archives: https://lists.opensuse.org/archives/list/doc@lists.ope nsuse.org
participants (2)
-
Attila Pinter -
TomasK