[opensuse-wiki] Why is this acceptable?
I do not understand decisions such as documented in https://en.opensuse.org/Icecream, "The documentation used to live in this page, but moved into a markdown README hosted under https://github.com/icecc/icecream. To report an issue or fix a problem, use github. You can fork the repo to edit the README.md just fine." -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On 12/28/2016 03:10 AM, PatrickD Garvey wrote:
I do not understand decisions such as documented in https://en.opensuse.org/Icecream, "The documentation used to live in this page, but moved into a markdown README hosted under https://github.com/icecc/icecream. To report an issue or fix a problem, use github. You can fork the repo to edit the README.md just fine."
First of all, this is the first time I hear about Icecream and I don't know the developers. That been said, I perfectly understand they moved the documentation to Github. 1) Github is the platform where the real development of Icecream happens. It's simply natural for developers to use the same mechanisms (pull requests) and platform to maintain the documentation. 2) On the other hand, almost everybody on the open source (and/or free software) universe is using Github nowadays. Everybody who is in the position to help (developers and users) is used to Github and, most likely, has an account there. You don't need an openSUSE account to contribute documentation. 3) The content in Github is way more visible than the one at our wiki. The openSUSE wiki is kind of a niche that only we use (and that we are using less and less, IMHO). Try to search something in Google (or any other popular search engine) that is both in Github and in our wiki. The first one will be found and in a high position, for the latter I'm not so sure. In short, IMHO Github is the natural choice to keep the documentation of a software project. We shouldn't be surprised if people moves away from the openSUSE wiki for that purpose. Cheers. -- Ancor González Sosa YaST Team at SUSE Linux GmbH -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On Thu, Dec 29, 2016 at 12:40 AM, Ancor Gonzalez Sosa <ancor@suse.de> wrote:
On 12/28/2016 03:10 AM, PatrickD Garvey wrote:
I do not understand decisions such as documented in https://en.opensuse.org/Icecream, "The documentation used to live in this page, but moved into a markdown README hosted under https://github.com/icecc/icecream. To report an issue or fix a problem, use github. You can fork the repo to edit the README.md just fine."
First of all, this is the first time I hear about Icecream and I don't know the developers. That been said, I perfectly understand they moved the documentation to Github.
1) Github is the platform where the real development of Icecream happens. It's simply natural for developers to use the same mechanisms (pull requests) and platform to maintain the documentation.
2) On the other hand, almost everybody on the open source (and/or free software) universe is using Github nowadays. Everybody who is in the position to help (developers and users) is used to Github and, most likely, has an account there. You don't need an openSUSE account to contribute documentation.
3) The content in Github is way more visible than the one at our wiki. The openSUSE wiki is kind of a niche that only we use (and that we are using less and less, IMHO). Try to search something in Google (or any other popular search engine) that is both in Github and in our wiki. The first one will be found and in a high position, for the latter I'm not so sure.
In short, IMHO Github is the natural choice to keep the documentation of a software project. We shouldn't be surprised if people moves away from the openSUSE wiki for that purpose.
Cheers. -- Ancor González Sosa YaST Team at SUSE Linux GmbH
OK, I thought that would be the basic direction of an answer, but the openSUSE wiki article claims icecream is a SUSE LLC employee created program. Doesn't it lose that identity when it is hosted on GitHub.com? Shouldn't it be hosted on GitLab.SUSE.de? That is, to become an official SUSE product, it could be developed on GitHub if an individual so chose, but it would not be official until that individual issued a pull request and it was accepted. And, then there is the challenge of learning a new syntax to do an existing task. This makes the third syntax I've seen used in writing *SUSE documentation. Doc.openSUSE.org requires one to know how to use a proprietary variant of Docbook. En.openSUSE.org requires knowledge of WikiMediA syntax. And icecream is written in Markdown. And let's not leave out the desire to make this documentation available to an international audience. I'm not a translator, so I'm not that familiar with how many syntactical structures are required across the documentation variants, but I've seen emotional discussions when someone proposes a change in the translation workflow. All these "solutions" break the *SUSE community into smaller and smaller cooperative groups and increase the cost of producing a quality offering. That's the frustration generator for me. Respectfully, PatrickD -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
Gesendet: Donnerstag, 29. Dezember 2016 um 17:33 Uhr Von: "PatrickD Garvey" <patrickdgarveyt@gmail.com> An: "Ancor Gonzalez Sosa" <ancor@suse.de> Cc: "_openSUSE Wiki Mailing List - opensuse-wiki@opensuse.org" <opensuse-wiki@opensuse.org> Betreff: Re: [opensuse-wiki] Why is this acceptable?
OK, I thought that would be the basic direction of an answer, but the openSUSE wiki article claims icecream is a SUSE LLC employee created program. Doesn't it lose that identity when it is hosted on GitHub.com? Shouldn't it be hosted on GitLab.SUSE.de? That is, to become an official SUSE product, it could be developed on GitHub if an individual so chose, but it would not be official until that individual issued a pull request and it was accepted. It isn't important, whether github or gitlab will be used. Both platforms are using the same technology "git". Github is public and everybody can contribute. SUSE is an open source company and has moved most parts of software development from private infrastructure to github in the last years. Do you want to be able to work in the different projects (in documentation) or do you want to work only in the wiki without any knowledge about the special technology behind that all? I would prefer the first one.
And, then there is the challenge of learning a new syntax to do an existing task. This makes the third syntax I've seen used in writing *SUSE documentation. Doc.openSUSE.org requires one to know how to use a proprietary variant of Docbook. En.openSUSE.org requires knowledge of WikiMediA syntax. And icecream is written in Markdown.
That's the reason, why we have got different mailing lists and teams. You will use different technologies in different teams. I can add Weblate to your list (translation team). You can choose what you want to do and with what/ where you want to work with. I hadn't any knowledge about git in my first years at openSUSE, too. I contributed to teams where I knew the used technologies and it was easy to start there. Any time you will have a time stamp, where you want to know/ learn more and you will use other technologies, too. ;)
And let's not leave out the desire to make this documentation available to an international audience. I'm not a translator, so I'm not that familiar with how many syntactical structures are required across the documentation variants, but I've seen emotional discussions when someone proposes a change in the translation workflow. You will need improvements in workflows in communities like in companies. Tell us your ideas and we can use it, if it can make all better. You don't need to be a translator. You can improve/ update the documentation in the English wiki, too. That's one syntax. git isn't a big difference. After some time in our wiki you will understand similarities and use the other platform like naturally.
All these "solutions" break the *SUSE community into smaller and smaller cooperative groups and increase the cost of producing a quality offering. That's the frustration generator for me.
Respectfully, PatrickD -- We have got different groups for getting the quality and you can choose where you want to contribute. You don't need mixing it all! Being in one group is enough for the fist time. After that you can grow into other areas, too.
Best regards, Sarah -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On Fri, Dec 30, 2016 at 3:12 AM, Sarah Julia Kriesch <ada.lovelace@gmx.de> wrote:
Gesendet: Donnerstag, 29. Dezember 2016 um 17:33 Uhr Von: "PatrickD Garvey" <patrickdgarveyt@gmail.com> An: "Ancor Gonzalez Sosa" <ancor@suse.de> Cc: "_openSUSE Wiki Mailing List - opensuse-wiki@opensuse.org" <opensuse-wiki@opensuse.org> Betreff: Re: [opensuse-wiki] Why is this acceptable?
OK, I thought that would be the basic direction of an answer, but the openSUSE wiki article claims icecream is a SUSE LLC employee created program. Doesn't it lose that identity when it is hosted on GitHub.com? Shouldn't it be hosted on GitLab.SUSE.de? That is, to become an official SUSE product, it could be developed on GitHub if an individual so chose, but it would not be official until that individual issued a pull request and it was accepted. It isn't important, whether github or gitlab will be used. Both platforms are using the same technology "git". Github is public and everybody can contribute. SUSE is an open source company and has moved most parts of software development from private infrastructure to github in the last years. Do you want to be able to work in the different projects (in documentation) or do you want to work only in the wiki without any knowledge about the special technology behind that all? I would prefer the first one.
And, then there is the challenge of learning a new syntax to do an existing task. This makes the third syntax I've seen used in writing *SUSE documentation. Doc.openSUSE.org requires one to know how to use a proprietary variant of Docbook. En.openSUSE.org requires knowledge of WikiMediA syntax. And icecream is written in Markdown.
That's the reason, why we have got different mailing lists and teams. You will use different technologies in different teams. I can add Weblate to your list (translation team). You can choose what you want to do and with what/ where you want to work with. I hadn't any knowledge about git in my first years at openSUSE, too. I contributed to teams where I knew the used technologies and it was easy to start there. Any time you will have a time stamp, where you want to know/ learn more and you will use other technologies, too. ;)
And let's not leave out the desire to make this documentation available to an international audience. I'm not a translator, so I'm not that familiar with how many syntactical structures are required across the documentation variants, but I've seen emotional discussions when someone proposes a change in the translation workflow. You will need improvements in workflows in communities like in companies. Tell us your ideas and we can use it, if it can make all better. You don't need to be a translator. You can improve/ update the documentation in the English wiki, too. That's one syntax. git isn't a big difference. After some time in our wiki you will understand similarities and use the other platform like naturally.
All these "solutions" break the *SUSE community into smaller and smaller cooperative groups and increase the cost of producing a quality offering. That's the frustration generator for me.
Respectfully, PatrickD -- We have got different groups for getting the quality and you can choose where you want to contribute. You don't need mixing it all! Being in one group is enough for the fist time. After that you can grow into other areas, too.
Best regards, Sarah
Sarah, To put my response to your reply succinctly, you're not seeing the world through my eyes. As I understand it, your perception of the variety of tools used to accomplish the tasks required to support the openSUSE project and the SUSE product is an opportunity to learn many things. My perception is each learning opportunity is a use of time that is needed to produce the components of the project/product that is non-productive if one has already learned a tool and it's syntax that does the job. Learning a second, third, fourth, fifth, sixth, seventh, ... documentation tool is non-productive when my objective is to provide high quality documentation. The fact there are three different syntax's that are used by three different documentation producing sub-communities also increases the effort required to coordinate the work of those sub-communities such that the same documentation is produced only once, not three times. The fact there is a link in the openSUSE wiki to a GitHub file indicates it takes an unnecessary expenditure of time for a new member of the openSUSE project just to locate the documentation, let alone keep it up to date. Producing software products is still a very labor-intensive process. Diverting available time to repeated re-learning of a mastered skill is a serious cost to the quality, as well as the quantity, of the output. -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On 2016-12-30 19:34, PatrickD Garvey wrote:
On Fri, Dec 30, 2016 at 3:12 AM, Sarah Julia Kriesch <> wrote:
Sarah, To put my response to your reply succinctly, you're not seeing the world through my eyes.
As I understand it, your perception of the variety of tools used to accomplish the tasks required to support the openSUSE project and the SUSE product is an opportunity to learn many things. My perception is each learning opportunity is a use of time that is needed to produce the components of the project/product that is non-productive if one has already learned a tool and it's syntax that does the job.
Learning a second, third, fourth, fifth, sixth, seventh, ... documentation tool is non-productive when my objective is to provide high quality documentation. The fact there are three different syntax's that are used by three different documentation producing sub-communities also increases the effort required to coordinate the work of those sub-communities such that the same documentation is produced only once, not three times. The fact there is a link in the openSUSE wiki to a GitHub file indicates it takes an unnecessary expenditure of time for a new member of the openSUSE project just to locate the documentation, let alone keep it up to date.
Producing software products is still a very labor-intensive process. Diverting available time to repeated re-learning of a mastered skill is a serious cost to the quality, as well as the quantity, of the output.
With my user and tech writer hat on, I agree. -- Cheers / Saludos, Carlos E. R. (from 42.2 x86_64 "Malachite" at Telcontar)
Gesendet: Freitag, 30. Dezember 2016 um 23:00 Uhr Von: "Carlos E. R." <robin.listas@telefonica.net> An: opensuse-wiki@opensuse.org Betreff: Re: [opensuse-wiki] Why is this acceptable?
On 2016-12-30 19:34, PatrickD Garvey wrote:
On Fri, Dec 30, 2016 at 3:12 AM, Sarah Julia Kriesch <> wrote:
Sarah, To put my response to your reply succinctly, you're not seeing the world through my eyes.
As I understand it, your perception of the variety of tools used to accomplish the tasks required to support the openSUSE project and the SUSE product is an opportunity to learn many things. My perception is each learning opportunity is a use of time that is needed to produce the components of the project/product that is non-productive if one has already learned a tool and it's syntax that does the job.
Learning a second, third, fourth, fifth, sixth, seventh, ... documentation tool is non-productive when my objective is to provide high quality documentation. The fact there are three different syntax's that are used by three different documentation producing sub-communities also increases the effort required to coordinate the work of those sub-communities such that the same documentation is produced only once, not three times. The fact there is a link in the openSUSE wiki to a GitHub file indicates it takes an unnecessary expenditure of time for a new member of the openSUSE project just to locate the documentation, let alone keep it up to date.
Producing software products is still a very labor-intensive process. Diverting available time to repeated re-learning of a mastered skill is a serious cost to the quality, as well as the quantity, of the output.
With my user and tech writer hat on, I agree.
-- Cheers / Saludos,
Carlos E. R. Thanks for your feedback!
You read the view of a Software Developer by Ancor (YaST Developer at SUSE), too. @Ancor: Thanks that you answered the question with Github of the view of somebody in the Development at SUSE. :-) Open Source Developers are using Github and write their documentation there. Ancor and the YaST Team are doing that for YaST here: http://yast.github.io/documentation The normal user (user of openSUSE) wants to use a wiki of their Linux distribution. That can give the best overview about the operating system. We (wiki Team) are responsible for updating it. We don't have many Developers on the mailing list. That was the reason for linking the Github documentation on the wiki page. It is difficult to get a Developer for writing his documentation on both portals (Github and wiki). They have got the same meaning like you as a Technical Writer. They want to use one platform and commit their code and documentation on one way. I have got the view of a System Administrator: I want to have happy cumstomers and developers! What can I do for having both? I view the work of developers on Github/ mailing list/ release notes until now and updated the wiki. I live freedom, that everybody can contribute where he likes. One Slogan I learned in my first job: "Happy cows give better milk!" Is the cow more happy while running free or being locked-in? You can transfer it to an open source project: -> Happy Developers (with freedom) develop better software. -> Happy System Administrators (with freedom) make better system administration. -> Happy Technical Writers (with freedom) write better documentations. Now we have got the questions, why we have got a third documentation tool. This tool can create a completely documentation in pdf. Some customers want to have a printed or pdf version of a documentation. Every other distrubtion has got it beside of their wiki, too. The Documentation Team at SUSE is doing most parts of this job at the moment. We should ask Christoph of this team after his view and meaning about documentations with different tools. @Christoph: How is your job with different tools (wiki/ doc/ Github)? Do you have ideas for improvements? I want to have meanings of all different views in our wiki team before finding a solution. I want to have happy Contributors in our wiki Team. ;-) Enjoy the last hours of this year and have a happy new year! Best regards, Sarah -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On 2016-12-31 13:51, Sarah Julia Kriesch wrote:
Gesendet: Freitag, 30. Dezember 2016 um 23:00 Uhr Von: "Carlos E. R." <robin.listas@telefonica.net>
...
Producing software products is still a very labor-intensive process. Diverting available time to repeated re-learning of a mastered skill is a serious cost to the quality, as well as the quantity, of the output.
With my user and tech writer hat on, I agree.
Thanks for your feedback!
Welcome :-)
You read the view of a Software Developer by Ancor (YaST Developer at SUSE), too. @Ancor: Thanks that you answered the question with Github of the view of somebody in the Development at SUSE. :-)
Open Source Developers are using Github and write their documentation there. Ancor and the YaST Team are doing that for YaST here: http://yast.github.io/documentation
The normal user (user of openSUSE) wants to use a wiki of their Linux distribution. That can give the best overview about the operating system. We (wiki Team) are responsible for updating it. We don't have many Developers on the mailing list. That was the reason for linking the Github documentation on the wiki page. It is difficult to get a Developer for writing his documentation on both portals (Github and wiki). They have got the same meaning like you as a Technical Writer. They want to use one platform and commit their code and documentation on one way.
I have got the view of a System Administrator: I want to have happy cumstomers and developers! What can I do for having both? I view the work of developers on Github/ mailing list/ release notes until now and updated the wiki. I live freedom, that everybody can contribute where he likes.
Yes, I can well understand they don't wish to write documentation in several different platforms.
One Slogan I learned in my first job: "Happy cows give better milk!" Is the cow more happy while running free or being locked-in? You can transfer it to an open source project: -> Happy Developers (with freedom) develop better software. -> Happy System Administrators (with freedom) make better system administration. -> Happy Technical Writers (with freedom) write better documentations.
Now we have got the questions, why we have got a third documentation tool. This tool can create a completely documentation in pdf. Some customers want to have a printed or pdf version of a documentation. Every other distrubtion has got it beside of their wiki, too. The Documentation Team at SUSE is doing most parts of this job at the moment. We should ask Christoph of this team after his view and meaning about documentations with different tools. @Christoph: How is your job with different tools (wiki/ doc/ Github)? Do you have ideas for improvements?
I want to have meanings of all different views in our wiki team before finding a solution. I want to have happy Contributors in our wiki Team. ;-)
Me, I find writing on the wiki a bit cumbersome, but it is an easy access place for both writers and readers. -- Cheers / Saludos, Carlos E. R. (from 42.2 x86_64 "Malachite" at Telcontar)
Gesendet: Samstag, 31. Dezember 2016 um 15:30 Uhr Von: "Carlos E. R." <robin.listas@telefonica.net> An: opensuse-wiki@opensuse.org Betreff: Re: [opensuse-wiki] Why is this acceptable?
On 2016-12-31 13:51, Sarah Julia Kriesch wrote:
Gesendet: Freitag, 30. Dezember 2016 um 23:00 Uhr Von: "Carlos E. R." <robin.listas@telefonica.net>
...
Producing software products is still a very labor-intensive process. Diverting available time to repeated re-learning of a mastered skill is a serious cost to the quality, as well as the quantity, of the output.
With my user and tech writer hat on, I agree.
Thanks for your feedback!
Welcome :-)
You read the view of a Software Developer by Ancor (YaST Developer at SUSE), too. @Ancor: Thanks that you answered the question with Github of the view of somebody in the Development at SUSE. :-)
Open Source Developers are using Github and write their documentation there. Ancor and the YaST Team are doing that for YaST here: http://yast.github.io/documentation
The normal user (user of openSUSE) wants to use a wiki of their Linux distribution. That can give the best overview about the operating system. We (wiki Team) are responsible for updating it. We don't have many Developers on the mailing list. That was the reason for linking the Github documentation on the wiki page. It is difficult to get a Developer for writing his documentation on both portals (Github and wiki). They have got the same meaning like you as a Technical Writer. They want to use one platform and commit their code and documentation on one way.
I have got the view of a System Administrator: I want to have happy cumstomers and developers! What can I do for having both? I view the work of developers on Github/ mailing list/ release notes until now and updated the wiki. I live freedom, that everybody can contribute where he likes.
Yes, I can well understand they don't wish to write documentation in several different platforms.
One Slogan I learned in my first job: "Happy cows give better milk!" Is the cow more happy while running free or being locked-in? You can transfer it to an open source project: -> Happy Developers (with freedom) develop better software. -> Happy System Administrators (with freedom) make better system administration. -> Happy Technical Writers (with freedom) write better documentations.
Now we have got the questions, why we have got a third documentation tool. This tool can create a completely documentation in pdf. Some customers want to have a printed or pdf version of a documentation. Every other distrubtion has got it beside of their wiki, too. The Documentation Team at SUSE is doing most parts of this job at the moment. We should ask Christoph of this team after his view and meaning about documentations with different tools. @Christoph: How is your job with different tools (wiki/ doc/ Github)? Do you have ideas for improvements?
I want to have meanings of all different views in our wiki team before finding a solution. I want to have happy Contributors in our wiki Team. ;-)
Me, I find writing on the wiki a bit cumbersome, but it is an easy access place for both writers and readers.
Can you describe what "a bit cumbersome" is? You can fix only issues, if you know the problem. Best regards, Sarah -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On 2016-12-31 17:53, Sarah Julia Kriesch wrote:
Me, I find writing on the wiki a bit cumbersome, but it is an easy access place for both writers and readers.
Can you describe what "a bit cumbersome" is? You can fix only issues, if you know the problem.
No, there is no way to repair that, it is by design of a "wiki" system. For instance, it is not WYSIWYG. One has to know "keywords" that should result in a certain format, then ask the system to produce the output and see the result. If it is not as wanted, change and repeat procedure. -- Cheers / Saludos, Carlos E. R. (from 42.2 x86_64 "Malachite" at Telcontar)
Hello, Am Dienstag, 3. Januar 2017, 16:40:14 CET schrieb Carlos E. R.:
On 2016-12-31 17:53, Sarah Julia Kriesch wrote:
Me, I find writing on the wiki a bit cumbersome, but it is an easy access place for both writers and readers.
Can you describe what "a bit cumbersome" is? You can fix only issues, if you know the problem.
No, there is no way to repair that, it is by design of a "wiki" system. For instance, it is not WYSIWYG.
One has to know "keywords" that should result in a certain format, then ask the system to produce the output and see the result. If it is not as wanted, change and repeat procedure.
Time for a funny story ;-) I'm admin on two wikis for gardeners and wine growers. When I set up those wikis, I showed them a WYSIWYG editor that (back then) worked with MediaWiki. After some testing, the surprising result was that they prefer to edit wiki source, and IIRC the reason was because "it's easier". Yes, really! This makes the wish for a WYSIWYG editor for the openSUSE wiki (which is edited by people who much more "computer stuff" than a typical gardener) somewhat funny ;-) If there is really a demand for a WYSIWYG editor, I can of course check what's available, if it fits our needs and doesn't get in the way of people who prefer to edit wiki source. (From a quick look, https://www.mediawiki.org/wiki/VisualEditor might be a good candidate.) However, can we please do this after the wiki migration and update is done? I already had some fun with all the extensions we use [1], and updating everything to a new version already gives enough chances to break something. Therefore I'd prefer not to add another extension to the mix to avoid delays ;-) Regards, Christian Boltz PS: To avoid another mail about the "Mr./Ms." - well, it depends ;-) If you write to someone the first time, using "Mr./Ms." is not really bad, and nobody will hate you for that. Maybe that person just thinks you are a bit too formal and/or not too familiar with the open source community. But if you always used the first name and suddenly switch to "Mr./ Ms.", well... ;-) [1] To keep the "This page has been accessed NNNN times." footer [2], I had to fix another extension. Migrating the openSUSE theme to the latest MediaWiki also was a funny[tm] task ;-) [2] This feature is no longer part of MediaWiki and now available as the HitCounters extension. -- Kann bitte jemand ein "Dumme Ideen Limit" für Politiker einführen? 1 dumme Idee pro Jahr klingt gut. Dann is Öttinger bis an sein Lebensende nämlich ruhig, da er seinen Vorat schon verbraucht hat... [Michael Schlesiger zu https://plus.google.com/+KristianKöhntopp/posts/LMX1JWg6DfS] -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On 2017-01-03 18:39, Christian Boltz wrote:
Am Dienstag, 3. Januar 2017, 16:40:14 CET schrieb Carlos E. R.:
Can you describe what "a bit cumbersome" is? You can fix only issues, if you know the problem.
No, there is no way to repair that, it is by design of a "wiki" system. For instance, it is not WYSIWYG.
One has to know "keywords" that should result in a certain format, then ask the system to produce the output and see the result. If it is not as wanted, change and repeat procedure.
Time for a funny story ;-)
I'm admin on two wikis for gardeners and wine growers. When I set up those wikis, I showed them a WYSIWYG editor that (back then) worked with MediaWiki.
After some testing, the surprising result was that they prefer to edit wiki source, and IIRC the reason was because "it's easier". Yes, really!
This makes the wish for a WYSIWYG editor for the openSUSE wiki (which is edited by people who much more "computer stuff" than a typical gardener) somewhat funny ;-)
Understandable :-) Yet most of us use L.Office Writer ;-) In the past I used editors that would switch view mode (tokens or graphic) with a keypress. Both modes are useful. But an online editor is typically also slow to react. That said, my preferred tool is LyX.
If there is really a demand for a WYSIWYG editor, I can of course check what's available, if it fits our needs and doesn't get in the way of people who prefer to edit wiki source. (From a quick look, https://www.mediawiki.org/wiki/VisualEditor might be a good candidate.)
However, can we please do this after the wiki migration and update is done? I already had some fun with all the extensions we use [1], and updating everything to a new version already gives enough chances to break something. Therefore I'd prefer not to add another extension to the mix to avoid delays ;-)
Yes, of course. I'm not in any hurry either, and I write very few wiki pages, so don't base decisions on me alone.
PS: To avoid another mail about the "Mr./Ms." - well, it depends ;-) If you write to someone the first time, using "Mr./Ms." is not really bad, and nobody will hate you for that. Maybe that person just thinks you are a bit too formal and/or not too familiar with the open source community. But if you always used the first name and suddenly switch to "Mr./ Ms.", well... ;-)
Oh :-( Then somebody may be a bit pissed at me for that reason, unbeknown to me. :-( - -- Cheers / Saludos, Carlos E. R. (from 13.1 x86_64 "Bottle" (Minas Tirith)) -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iF4EAREIAAYFAlhr7FkACgkQja8UbcUWM1z+pgEAl5yEu+gvdTiVQp2eOxq/XkXW KlEQJUufSPy7lSlxjTAA/1gL7S9Pq7IHGCsizeYlhN9JV/nb0O+R889NIYdGF1n3 =wJPH -----END PGP SIGNATURE----- -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
Ms. Kriesch, Please let me try again to share the essence of my world view: Why do you use the character string "Sarah Julia Kriesch" in the From: field of your email? Are you not free to use only the character string "ada.lovelace@" and a domain name to make the email system properly deliver your writing? -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
Gesendet: Sonntag, 01. Januar 2017 um 17:55 Uhr Von: "PatrickD Garvey" <patrickdgarveyt@gmail.com> An: "Sarah Julia Kriesch" <ada.lovelace@gmx.de> Cc: "_openSUSE Wiki Mailing List - opensuse-wiki@opensuse.org" <opensuse-wiki@opensuse.org> Betreff: Re: [opensuse-wiki] Why is this acceptable?
Ms. Kriesch,
Please let me try again to share the essence of my world view:
Why do you use the character string "Sarah Julia Kriesch" in the From: field of your email? Are you not free to use only the character string "ada.lovelace@" and a domain name to make the email system properly deliver your writing?
Why do you say "Ms. Kriesch"? We are a community and speak with our first names. I am a volunteer like you and I want to speak with you as an equal. Sarah Julia Kriesch is my real name and AdaLovelace my nick name in the community. Most Community Members are using their real names on mailing lists, just as I. I have a special email alias for openSUSE that it won't be mixed with private mails. I use another name as a nick name, because my education company wasn't allowed to know my contributions at openSUSE 5 years ago. They didn't want to see me in any open source communities. My online (community) friends said, I should use this nick name, because I would have the same CV like Ada Lovelace. She wasn't allowed to work in Computer Science and did it for her own. I did that (self-studying and with support in communities), too. That is a long time ago now. I use my nick name combined with my real name. All people in the community know me with my real name. Does that explain all? Best regards, Sarah -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On Sun, Jan 1, 2017 at 1:02 PM, Sarah Julia Kriesch <ada.lovelace@gmx.de> wrote:
Gesendet: Sonntag, 01. Januar 2017 um 17:55 Uhr Von: "PatrickD Garvey" <patrickdgarveyt@gmail.com> An: "Sarah Julia Kriesch" <ada.lovelace@gmx.de> Cc: "_openSUSE Wiki Mailing List - opensuse-wiki@opensuse.org" <opensuse-wiki@opensuse.org> Betreff: Re: [opensuse-wiki] Why is this acceptable?
Ms. Kriesch,
Please let me try again to share the essence of my world view:
Why do you use the character string "Sarah Julia Kriesch" in the From: field of your email? Are you not free to use only the character string "ada.lovelace@" and a domain name to make the email system properly deliver your writing?
Why do you say "Ms. Kriesch"? We are a community and speak with our first names. I am a volunteer like you and I want to speak with you as an equal.
Sarah Julia Kriesch is my real name and AdaLovelace my nick name in the community. Most Community Members are using their real names on mailing lists, just as I. I have a special email alias for openSUSE that it won't be mixed with private mails.
I use another name as a nick name, because my education company wasn't allowed to know my contributions at openSUSE 5 years ago. They didn't want to see me in any open source communities. My online (community) friends said, I should use this nick name, because I would have the same CV like Ada Lovelace. She wasn't allowed to work in Computer Science and did it for her own. I did that (self-studying and with support in communities), too. That is a long time ago now. I use my nick name combined with my real name. All people in the community know me with my real name.
Does that explain all?
Best regards, Sarah
Yes, thank you, it does explain all I need to know to illustrate the point I'm trying to share with you. When one joins a group of other people for a purpose, one expects to do some things that the group thinks are important, like keep your private life disconnected from your corporate life in some cases and associate it for the benefit of both in other cases, depending upon the groups involved. I would like to suggest that one of the things one should expect to do when one joins a GNU/Linux distribution project is store one's output somewhere that is obviously linked with the project, not on some community server not associated with the project. I think I should store anything I do for the openSUSE project somewhere in the openSUSE.org domain, not in a RedHat.org or Canonical.org domain or a SourceForge.net or GitHub.com domain. Does that seem reasonable to you? -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
Gesendet: Sonntag, 01. Januar 2017 um 23:16 Uhr Von: "PatrickD Garvey" <patrickdgarveyt@gmail.com> An: "Sarah Julia Kriesch" <ada.lovelace@gmx.de> Cc: "_openSUSE Wiki Mailing List - opensuse-wiki@opensuse.org" <opensuse-wiki@opensuse.org> Betreff: Re: [opensuse-wiki] Why is this acceptable?
On Sun, Jan 1, 2017 at 1:02 PM, Sarah Julia Kriesch <ada.lovelace@gmx.de> wrote:
When one joins a group of other people for a purpose, one expects to do some things that the group thinks are important, like keep your private life disconnected from your corporate life in some cases and associate it for the benefit of both in other cases, depending upon the groups involved.
I would like to suggest that one of the things one should expect to do when one joins a GNU/Linux distribution project is store one's output somewhere that is obviously linked with the project, not on some community server not associated with the project. I think I should store anything I do for the openSUSE project somewhere in the openSUSE.org domain, not in a RedHat.org or Canonical.org domain or a SourceForge.net or GitHub.com domain.
Does that seem reasonable to you? -- openSUSE is an organization on Github and has got all projects there like other open source projects, too. You can see ( https://github.com/opensuse/ ) that is associated with the project. We have got - additional to that - our own infrastructure incl. wiki server. These servers are running with opensuse.org domains. We wouldn't use RedHat or Canonical any time, because they aren't sponsors of openSUSE. Our infrastructure is hosted by SUSE.
Your output will be stored, too. You get points for your work and any time you can apply for a Membership. Your wiki output can be watched here: https://en.opensuse.org/Special:Contributions/PatrickDGarvey Our social network which will also used for membership applications is here: https://connect.opensuse.org We do the same like other GNU/ Linux distribution projects like Fedora and Debian. -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On Mon, Jan 2, 2017 at 3:08 AM, Sarah Julia Kriesch <ada.lovelace@gmx.de> wrote:
Gesendet: Sonntag, 01. Januar 2017 um 23:16 Uhr Von: "PatrickD Garvey" <patrickdgarveyt@gmail.com> An: "Sarah Julia Kriesch" <ada.lovelace@gmx.de> Cc: "_openSUSE Wiki Mailing List - opensuse-wiki@opensuse.org" <opensuse-wiki@opensuse.org> Betreff: Re: [opensuse-wiki] Why is this acceptable?
On Sun, Jan 1, 2017 at 1:02 PM, Sarah Julia Kriesch <ada.lovelace@gmx.de> wrote:
When one joins a group of other people for a purpose, one expects to do some things that the group thinks are important, like keep your private life disconnected from your corporate life in some cases and associate it for the benefit of both in other cases, depending upon the groups involved.
I would like to suggest that one of the things one should expect to do when one joins a GNU/Linux distribution project is store one's output somewhere that is obviously linked with the project, not on some community server not associated with the project. I think I should store anything I do for the openSUSE project somewhere in the openSUSE.org domain, not in a RedHat.org or Canonical.org domain or a SourceForge.net or GitHub.com domain.
Does that seem reasonable to you? -- openSUSE is an organization on Github and has got all projects there like other open source projects, too. You can see ( https://github.com/opensuse/ ) that is associated with the project. We have got - additional to that - our own infrastructure incl. wiki server. These servers are running with opensuse.org domains. We wouldn't use RedHat or Canonical any time, because they aren't sponsors of openSUSE. Our infrastructure is hosted by SUSE.
Your output will be stored, too. You get points for your work and any time you can apply for a Membership. Your wiki output can be watched here: https://en.opensuse.org/Special:Contributions/PatrickDGarvey
Our social network which will also used for membership applications is here: https://connect.opensuse.org We do the same like other GNU/ Linux distribution projects like Fedora and Debian.
"openSUSE is an organization on Github and has got all projects there" Do you mean to imply that every source file that began life as part of the openSUSE project and continues to be developed in the openSUSE project can be found in the https://github.com/opensuse/ structure? (Just looking for complete communication of your world view, here. I'm sorry my writing often slips into what appears to be criticism, but it's really just seeking clear communication.) -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
Helllo, Am Sonntag, 1. Januar 2017, 14:16:44 CET schrieb PatrickD Garvey:
On Sun, Jan 1, 2017 at 1:02 PM, Sarah Julia Kriesch wrote:
Why do you say "Ms. Kriesch"? We are a community and speak with our first names. I am a volunteer like you and I want to speak with you as an equal.
I even heard people joking that saying "Mr./Ms. $lastname" to someone in an open source project is a way to show you are mad at them ;-)
Yes, thank you, it does explain all I need to know to illustrate the point I'm trying to share with you.
When one joins a group of other people for a purpose, one expects to do some things that the group thinks are important, like keep your private life disconnected from your corporate life in some cases and associate it for the benefit of both in other cases, depending upon the groups involved.
I would like to suggest that one of the things one should expect to do when one joins a GNU/Linux distribution project is store one's output somewhere that is obviously linked with the project, not on some community server not associated with the project. I think I should store anything I do for the openSUSE project somewhere in the openSUSE.org domain, not in a RedHat.org or Canonical.org domain or a SourceForge.net or GitHub.com domain.
You are overlooking an important point here - collaboration. It doesn't make sense to think of "we" vs. "them" when it comes to other distributions or upstream projects. It's quite the opposite - everybody can save time by working together with other distributions, upstream projects etc. We have more important things to do than re-inventing the wheel just because we need a green one. As an example: You might know that I maintain AppArmor in openSUSE and also contribute upstream (OMG, the upstream mailinglist is @lists.ubuntu.com, not at a "neutral" domain!) Some not-so-known details: - I implemented support for new AppArmor rule types (dbus, signal etc.) in aa-logprof, but those are not yet supported in the upstream kernel (and also not in openSUSE) - so currently only Ubuntu users benefit from that - I always send patches upstream so that everybody can benefit (no, saying "use openSUSE, it's fixed there" is not a good idea ;-) - In 2015, I visited DebConf (I'd guess I was the only one there who had never used Debian before) and even gave a talk. - I closely follow AppArmor-related bugreports in Debian and Ubuntu, and help them to get things fixed - even if it's distro-specific So, tell me - am I working for the enemy? ;-) BTW: This isn't a one way road. Quite some AppArmor contributions done by Ubuntu (some other upstream developers work for Canonical) and Debian contributors end up in openSUSE :-) Needless to say that AppArmor is just an example. What I said is basically valid for every package, project, whatever. Either you collaborate (and everybody wins), or you "cook your own soup" and never find out that someone else has a receipe for a much more tasty soup ;-) To come back to the origin of this discussion: I don't care too much _where_ the Icecream developers host their documentation as long as - it is complete and up to date (having it at the developers' favorite place makes this more likely) - it can be easily found (also not a problem, it's linked from the wiki, and your favorite search engine will also find it) I see the main purpose of the openSUSE wiki to provide openSUSE-specific information. Information about upstream projects (even if a project is done by openSUSE) is "nice to have", but it's also ok if it lives upstream. It's better have one good upstream documentation than pages at 5 distro wikis that are all incomplete and out of date ;-)
Does that seem reasonable to you?
Please answer that yourself after reading the above ;-) Regards, Christian Boltz PS: It seems my sigmonster [1] wanted to show an example of a bad place for storing documentation ;-) (To make sure you get it right: The problem is not Henne, the problem is that someone's brain is a bit hard to read by others ;-) [1] That's my script which randomly selects the signatures under my mails - and sometimes I start to think it isn't as random as I'd expect ;-) -- <suseROCKs> henne: [...] Can you link me to any documentation [...]? <henne> suseROCKs: brain://henne/hardware/touchsmart <suseROCKs> Firefox: Oops! There appears to be no brain:// associated with henne [from #opensuse-project] -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On 2017-01-02 14:43, Christian Boltz wrote:
Helllo,
Am Sonntag, 1. Januar 2017, 14:16:44 CET schrieb PatrickD Garvey:
On Sun, Jan 1, 2017 at 1:02 PM, Sarah Julia Kriesch wrote:
Why do you say "Ms. Kriesch"? We are a community and speak with our first names. I am a volunteer like you and I want to speak with you as an equal.
I even heard people joking that saying "Mr./Ms. $lastname" to someone in an open source project is a way to show you are mad at them ;-)
Oh, crumbs. I have used "Mr" often as a sign of respect. You mean it is not? Oh, my. :-( -- Cheers / Saludos, Carlos E. R. (from 42.2 x86_64 "Malachite" at Telcontar)
Sarah Julia Kriesch <ada.lovelace@gmx.de> wrote:
Gesendet: Sonntag, 01. Januar 2017 um 17:55 Uhr Von: "PatrickD Garvey" <patrickdgarveyt@gmail.com> An: "Sarah Julia Kriesch" <ada.lovelace@gmx.de> Cc: "_openSUSE Wiki Mailing List - opensuse-wiki@opensuse.org" <opensuse-wiki@opensuse.org> Betreff: Re: [opensuse-wiki] Why is this acceptable?
Ms. Kriesch,
Please let me try again to share the essence of my world view:
Why do you use the character string "Sarah Julia Kriesch" in the From: field of your email? Are you not free to use only the character string "ada.lovelace@" and a domain name to make the email system properly deliver your writing?
Why do you say "Ms. Kriesch"? We are a community and speak with our first names. I am a volunteer like you and I want to speak with you as an equal.
Sarah Julia Kriesch is my real name and AdaLovelace my nick name in the community. Most Community Members are using their real names on mailing lists, just as I. I have a special email alias for openSUSE that it won't be mixed with private mails.
I use another name as a nick name, because my education company wasn't allowed to know my contributions at openSUSE 5 years ago. They didn't want to see me in any open source communities. My online (community) friends said, I should use this nick name, because I would have the same CV like Ada Lovelace. She wasn't allowed to work in Computer Science and did it for her own. I did that (self-studying and with support in communities), too.
That's a really cool story behind the nickname ;-) She was an amazing lady and (just in case anyone didn't know already) arguably the first ever computer programmer: https://en.wikipedia.org/wiki/Ada_Lovelace -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On 12/31/2016 01:51 PM, Sarah Julia Kriesch wrote:
Gesendet: Freitag, 30. Dezember 2016 um 23:00 Uhr Von: "Carlos E. R." <robin.listas@telefonica.net> An: opensuse-wiki@opensuse.org Betreff: Re: [opensuse-wiki] Why is this acceptable?
On 2016-12-30 19:34, PatrickD Garvey wrote:
On Fri, Dec 30, 2016 at 3:12 AM, Sarah Julia Kriesch <> wrote:
Sarah, To put my response to your reply succinctly, you're not seeing the world through my eyes.
As I understand it, your perception of the variety of tools used to accomplish the tasks required to support the openSUSE project and the SUSE product is an opportunity to learn many things. My perception is each learning opportunity is a use of time that is needed to produce the components of the project/product that is non-productive if one has already learned a tool and it's syntax that does the job.
Learning a second, third, fourth, fifth, sixth, seventh, ... documentation tool is non-productive when my objective is to provide high quality documentation. The fact there are three different syntax's that are used by three different documentation producing sub-communities also increases the effort required to coordinate the work of those sub-communities such that the same documentation is produced only once, not three times. The fact there is a link in the openSUSE wiki to a GitHub file indicates it takes an unnecessary expenditure of time for a new member of the openSUSE project just to locate the documentation, let alone keep it up to date.
Producing software products is still a very labor-intensive process. Diverting available time to repeated re-learning of a mastered skill is a serious cost to the quality, as well as the quantity, of the output.
With my user and tech writer hat on, I agree.
-- Cheers / Saludos,
Carlos E. R. Thanks for your feedback!
You read the view of a Software Developer by Ancor (YaST Developer at SUSE), too. @Ancor: Thanks that you answered the question with Github of the view of somebody in the Development at SUSE. :-)
Open Source Developers are using Github and write their documentation there. Ancor and the YaST Team are doing that for YaST here: http://yast.github.io/documentation
Well, in fact we are using Github for the developer-oriented documentation and keeping the wiki for the user-oriented documentation. In my original mail I already explained why Github is the right place to reach potential developers. And it's not realistic to expect translated documentation for developers (they will have to communicate in English to get the patches accepted anyways). That's why we decided it was fine to leave the rather inconvenient (for our purposes) wiki behind. But just for developer doc. We don't plan to move the user documentation because we see the strengths of the wiki for that (it's a known central place, it's known by our community of translators, etc.).
The normal user (user of openSUSE) wants to use a wiki of their Linux distribution. That can give the best overview about the operating system. We (wiki Team) are responsible for updating it. We don't have many Developers on the mailing list. That was the reason for linking the Github documentation on the wiki page. It is difficult to get a Developer for writing his documentation on both portals (Github and wiki). They have got the same meaning like you as a Technical Writer. They want to use one platform and commit their code and documentation on one way.
If you want them to use any platform different than Markdown files at Github, you have to make sure the extra effort pays off for them.
I have got the view of a System Administrator: I want to have happy cumstomers and developers! What can I do for having both? I view the work of developers on Github/ mailing list/ release notes until now and updated the wiki. I live freedom, that everybody can contribute where he likes.
One Slogan I learned in my first job: "Happy cows give better milk!" Is the cow more happy while running free or being locked-in? You can transfer it to an open source project: -> Happy Developers (with freedom) develop better software. -> Happy System Administrators (with freedom) make better system administration. -> Happy Technical Writers (with freedom) write better documentations.
Now we have got the questions, why we have got a third documentation tool. This tool can create a completely documentation in pdf. Some customers want to have a printed or pdf version of a documentation. Every other distrubtion has got it beside of their wiki, too. The Documentation Team at SUSE is doing most parts of this job at the moment. We should ask Christoph of this team after his view and meaning about documentations with different tools. @Christoph: How is your job with different tools (wiki/ doc/ Github)? Do you have ideas for improvements?
I want to have meanings of all different views in our wiki team before finding a solution. I want to have happy Contributors in our wiki Team. ;-)
And if we are talking about variety of tools, don't forget we have two for translators: Weblate for translating software and the wiki for translating... well, for translating the wiki. Theoretically, Weblate is powerful enough to be used to translate different sources, including a Wiki, stuff coming from Github, etc. But that of course means that somebody needs to set the system. Tools... the never-ending strength/weakness of the openSUSE project...
Enjoy the last hours of this year and have a happy new year! Best regards, Sarah
Happy new year. -- Ancor González Sosa YaST Team at SUSE Linux GmbH -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
Gesendet: Montag, 02. Januar 2017 um 14:35 Uhr Von: "Ancor Gonzalez Sosa" <ancor@suse.de> An: opensuse-wiki@opensuse.org Betreff: Re: [opensuse-wiki] Why is this acceptable?
On 12/31/2016 01:51 PM, Sarah Julia Kriesch wrote:
Gesendet: Freitag, 30. Dezember 2016 um 23:00 Uhr Von: "Carlos E. R." <robin.listas@telefonica.net> An: opensuse-wiki@opensuse.org Betreff: Re: [opensuse-wiki] Why is this acceptable?
On 2016-12-30 19:34, PatrickD Garvey wrote:
On Fri, Dec 30, 2016 at 3:12 AM, Sarah Julia Kriesch <> wrote:
Sarah, To put my response to your reply succinctly, you're not seeing the world through my eyes.
As I understand it, your perception of the variety of tools used to accomplish the tasks required to support the openSUSE project and the SUSE product is an opportunity to learn many things. My perception is each learning opportunity is a use of time that is needed to produce the components of the project/product that is non-productive if one has already learned a tool and it's syntax that does the job.
Learning a second, third, fourth, fifth, sixth, seventh, ... documentation tool is non-productive when my objective is to provide high quality documentation. The fact there are three different syntax's that are used by three different documentation producing sub-communities also increases the effort required to coordinate the work of those sub-communities such that the same documentation is produced only once, not three times. The fact there is a link in the openSUSE wiki to a GitHub file indicates it takes an unnecessary expenditure of time for a new member of the openSUSE project just to locate the documentation, let alone keep it up to date.
Producing software products is still a very labor-intensive process. Diverting available time to repeated re-learning of a mastered skill is a serious cost to the quality, as well as the quantity, of the output.
With my user and tech writer hat on, I agree.
-- Cheers / Saludos,
Carlos E. R. Thanks for your feedback!
You read the view of a Software Developer by Ancor (YaST Developer at SUSE), too. @Ancor: Thanks that you answered the question with Github of the view of somebody in the Development at SUSE. :-)
Open Source Developers are using Github and write their documentation there. Ancor and the YaST Team are doing that for YaST here: http://yast.github.io/documentation
Well, in fact we are using Github for the developer-oriented documentation and keeping the wiki for the user-oriented documentation.
In my original mail I already explained why Github is the right place to reach potential developers. And it's not realistic to expect translated documentation for developers (they will have to communicate in English to get the patches accepted anyways). That's why we decided it was fine to leave the rather inconvenient (for our purposes) wiki behind. But just for developer doc.
We don't plan to move the user documentation because we see the strengths of the wiki for that (it's a known central place, it's known by our community of translators, etc.).
I would not move anything. I think about using plugins or anything else for copying content automatically after hearing all meanings. But I wouldn't do anything without a permit! I was surprised about the "too many tools" at first and after that Patrick wants to use Gitlab, because Github is public. I can understand the first meaning of a beginner at openSUSE. The second point isn't consequentally to the first point.
The normal user (user of openSUSE) wants to use a wiki of their Linux distribution. That can give the best overview about the operating system. We (wiki Team) are responsible for updating it. We don't have many Developers on the mailing list. That was the reason for linking the Github documentation on the wiki page. It is difficult to get a Developer for writing his documentation on both portals (Github and wiki). They have got the same meaning like you as a Technical Writer. They want to use one platform and commit their code and documentation on one way.
If you want them to use any platform different than Markdown files at Github, you have to make sure the extra effort pays off for them.
Christian and I setup a new wiki at the moment. I can bring this topic into our Heroes Meeting this Sunday, if we get an answer by the Documentation Team this week and I can summarize/ evaluate something for that.
I have got the view of a System Administrator: I want to have happy cumstomers and developers! What can I do for having both? I view the work of developers on Github/ mailing list/ release notes until now and updated the wiki. I live freedom, that everybody can contribute where he likes.
One Slogan I learned in my first job: "Happy cows give better milk!" Is the cow more happy while running free or being locked-in? You can transfer it to an open source project: -> Happy Developers (with freedom) develop better software. -> Happy System Administrators (with freedom) make better system administration. -> Happy Technical Writers (with freedom) write better documentations.
Now we have got the questions, why we have got a third documentation tool. This tool can create a completely documentation in pdf. Some customers want to have a printed or pdf version of a documentation. Every other distrubtion has got it beside of their wiki, too. The Documentation Team at SUSE is doing most parts of this job at the moment. We should ask Christoph of this team after his view and meaning about documentations with different tools. @Christoph: How is your job with different tools (wiki/ doc/ Github)? Do you have ideas for improvements?
I want to have meanings of all different views in our wiki team before finding a solution. I want to have happy Contributors in our wiki Team. ;-)
And if we are talking about variety of tools, don't forget we have two for translators: Weblate for translating software and the wiki for translating... well, for translating the wiki.
Psst! :-) We have got a separate mailing list for translators (with Weblate). Patrick wants to work in the Technical Documentation (English) and 3 tools are too much. We have to analyze the problem of Patrick and Carlos. We can add features into our new wiki instance (if needed). But I want to hear all before doing that. ;-)
Theoretically, Weblate is powerful enough to be used to translate different sources, including a Wiki, stuff coming from Github, etc. But that of course means that somebody needs to set the system.
Patrick doesn't want to translate...
Tools... the never-ending strength/weakness of the openSUSE project...
Enjoy the last hours of this year and have a happy new year! Best regards, Sarah
Happy new year.
-- Ancor González Sosa
I want to work based on the Software Development Life Cycle in all projects (unimportant whether technical or not technical). 1. Planning: Asking all after their problems and summarizing that. Looking after such processes in other teams or communities, whether something like that exists. 2. Analysis: Defining the problem and finding solutions/ plugins... 3. Design: Evaluating of solutions on test systems. We have got a test system at the moment. ;-) 4. Implementation/ Installation: Integration of the solution into our new wiki setup. 5. Testing: Testing it and asking, whether all are happy. :-) 6. Maintenance: Improving, if something has to be improved. Best regards, Sarah -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
Hello everybody, sorry for chiming in so late. I have been really busy. :-( On Sat, 31 Dec 2016 13:51:01 +0100 "Sarah Julia Kriesch" <ada.lovelace@gmx.de> wrote:
@Christoph: How is your job with different tools (wiki/ doc/ Github)?
That is a huge question. :-) Let me start with a little bit of background about the SUSE documentation team and our work. Obviously, we write documentation. The language we use is DocBook XML. There are alternatives such as AsciiDoc, reStructuredText, or Markdown. They are probably easier to learn and we thought about a migration more than once, but every time we decided to stick to DocBook because it is the only language that provides all the necessary features and covers all our use cases. I could go into the technical details, but let me just point out the main advantages of DocBook: 1. You can use XSLT stylesheets to convert DocBook into any output format you want. DAPS, our "DocBook Authoring and Publishing Suite" [1], currently supports HTML, PDF, plain text, man pages, epub, and mobi. 2. Stylesheets can also be used to apply a look or branding to the documentation. The SUSE and openSUSE documentation is built from the same sources and is (mostly) the same, but we use different stylesheets to make them look different. 3. You can use conditionals and entities. Conditionals can be used to include a something in say the SUSE documentation but not on openSUSE. Entities are variables which are used to things like product names, versions and alike. This allows us to share a large part of the documentation between SUSE and openSUSE. 4. You can use schemas to limit the elements writers are allowed to use. DocBook is huge and our stylesheets don't cover all the elements, so we only use a subset called GeekoDoc [2]. As you can see our whole toolchain is open source and freely available, starting from the source code on github [3] over the schemas [2] and stylesheets [4] to the tools to check and [5] to generate [1] the output. We also have two OBS repos with our tools, one for the stable releases [6] and one for development [7]. Every openSUSE user can contribute by sending pull requests [3].
Do you have ideas for improvements?
Frankly speaking I haven't yet thought about improvement much. I'm (more of less) happy with the current process and tooling, but that's me with my documentarian hat on. I can see why volunteers might see things differently. I think the important thing we need to keep in mind is that different people have different needs. While the SUSE documentation team needs something that can cater all output formats, somebody who only edits the wiki probably does not care. As you said "happy cows give better milk". For me this means we should allow everybody to do their work the way that works best for them. Unfortunately this also means that we end up with a variety of tools and languages, but that's just the way it is. If you want to drive a nail into a wall, you use a hammer and not a screwdriver. There is no use telling people to use screwdrivers. And I'm afraid there is no multi-tool either. For example, we could easily export DocBook documentation to the Wiki. There are already XSLT stylesheets for MediaWiki export. But I am not sure we want that. Before we decide to do so, we should think about two things: 1. What parts of the documentation should be in the wiki? A wiki is best suited for frequently changing information, e.g. a list of known bugs and workarounds. On the other hand, information that only changes with every release or not at all, should probably remain on docs.opensuse.org. 2. How would we handle feedback? One of the main advantages of the wiki is the low entry barrier. It is easy to edit, in fact, we encourage contributions and we are always looking for more feedback. So when we export something to the wiki, and some community members improve it there, how do we make sure this feedback is synced back to the documentation on GitHub? If we don't incorporate the changes, they will be overwritten by the next export and the volunteers are upset. If we tell them to submit a pull request upstream on GitHub, they have to learn yet another language and are probably upset, too. Again, there are different target audiences with different use cases. There is a reason why we have all these different tools and processes. I can understand that for some people this seems a mess, but I see it as diversity and a sign of a broad and active community. I'm all for better collaboration. So if anybody has any questions or suggestions about our tooling, I'm looking forward to hear them. Best regards, Christoph [1] https://opensuse.github.io/daps/ [2] https://github.com/openSUSE/geekodoc/ [3] https://github.com/SUSE/doc-sle/ [4] https://github.com/openSUSE/suse-xsl/ [5] https://github.com/openSUSE/suse-doc-style-checker/ [6] https://build.opensuse.org/project/show/Documentation:Tools [7] https://build.opensuse.org/project/show/Documentation:Tools:Develop -- Christoph Wickert <cwickert@suse.de> Technical Writer SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nürnberg Tel: +49-911-74053-0; Fax: +49-911-7417755; https://www.suse.com/ SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
On Tue, Jan 17, 2017 at 8:26 AM, Christoph Wickert <cwickert@suse.de> wrote:
Hello everybody,
sorry for chiming in so late. I have been really busy. :-(
On Sat, 31 Dec 2016 13:51:01 +0100 "Sarah Julia Kriesch" <ada.lovelace@gmx.de> wrote:
@Christoph: How is your job with different tools (wiki/ doc/ Github)?
That is a huge question. :-) Let me start with a little bit of background about the SUSE documentation team and our work.
Obviously, we write documentation. The language we use is DocBook XML. There are alternatives such as AsciiDoc, reStructuredText, or Markdown. They are probably easier to learn and we thought about a migration more than once, but every time we decided to stick to DocBook because it is the only language that provides all the necessary features and covers all our use cases.
Please allow me to ask a question so I am clear as to what you are saying about the SUSE documentation team. When SUSE LLC hires a new member of the SUSE documentation team, what documentation tool are they allowed to use to produce the SLES documentation? -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On Wed, 18 Jan 2017 15:23:29 -0800 PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
When SUSE LLC hires a new member of the SUSE documentation team, what documentation tool are they allowed to use to produce the SLES documentation?
Hi Patrick, we can to use any editor as long as it produces valid DocBook XML. This allows us to have long discussions about the old topic of vim vs. emacs :-) or just use Atom, gedit, or whatever. However DocBook as language is set. If I worked as a kernel developer, I had to write my code in C. This is not only a technical requirement as the kernel is written in C, but also a tribute to the people who actually wrote all that code over the last 25 years. If I wanted to write in a different language, I would have to convince people that my approach is superior. Given the size of the code and the kernel community, this is going to be tough, so I would probably have to start from scratch. If my project is successful, I can win people over. I hear Google is working on an OS written in their Go language. Let's see how that goes. Back to documentation: If I wanted to use something else but DocBook, I would have to convince my team, too. I know they are always open to improvements, so once I manage to convince them, they would support me and we would work on a migration path together. The same goes for us. We are always grateful for suggestions and I don't mind if they sound controversial. I will listen, provide feedback, listen again, etc., before I make a decision. And then it's on all of us to decide and reach consensus. But at the end of the day we will not reach a consensus by talking but by doing. The ones doing the work define the direction. If you write a wiki page, you define the content. To me, that's the very essence of Free Software: Nobody tells you what to do, you do what you do because you want it to happen. openSUSE is a community of equals. It doesn't matter if you are a volunteer or on SUSE's payroll, we all share the same goal: Improve openSUSE. And we get recognition for what we do. We lead by example and not by authority. Back to your initial question of whether it is acceptable that some information is moved from the wiki to GitHub. I think it is. First of all, the information was not openSUSE-specific. If we want a project like Icecream to succeed, it needs wide adoption, and this is better achieved on GitHub than on some openSUSE infrastructure. (In fact, I would like to see more projects that were started by SUSE employees or openSUSE become independent of the company and distribution because it allows participation from other people and communities. We have so many awesome tools in openSUSE, but we don't talk about them enough.) Last but not least it's not on us to decide where this documentation resides, but on the people who write and maintain it. Coolo, who moved the information, is also a developer of Icecream. As long as he gets the job done, nobody is to tell him what to do. We should support everything that makes it easier for him to get get his job done. If we consider Icecream documentation useful for openSUSE users, we can add it back to the wiki. In fact, you can just go ahead and do it, nobody will stop you. On the contrary, people will be grateful. But we should not just add and forget it. If none of us can make the commitment to maintain the wiki page, we should just trust the upstream developers. I think we all agree that a link to the recent version on GitHub is better than outdated information in the wiki. And this problem is not specific to the Icecream documentation. We should think carefully about what information should be on the wiki and what is better kept elsewhere. We should avoid duplication because we will not only duplicate information but also work, making it harder for both wiki editors and documentation writers to contribute. Instead, we should focus on bringing the relevant bits together and making them accessible to our users, e.g. through a smart search engine. So in order to to decide what belongs where, there are a few questions: 1. What is static and what keeps changing frequently? 2. What output formats do we need for a particular piece of information? 3. Where will our users find and use the information easily? Once we have these questions answered, we can move ahead. For me, the question is not "Why is this acceptable?" or "Is this acceptable?" but "Is this feasible?". Does it help us to make the wiki and openSUSE better? I will support everything that does and am looking forward to your suggestions. This call for feedback goes out to all of you wiki editors. Let me know what is missing from the wiki or our documentation. What is good, what needs to be improved? Just fire everything at me :) and I will see what the SUSE documentation team can do to help. Best regards, Christoph -- Christoph Wickert <cwickert@suse.de> Technical Writer SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nürnberg Tel: +49-911-74053-0; Fax: +49-911-7417755; https://www.suse.com/ SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <cwickert@suse.de> wrote:
On Wed, 18 Jan 2017 15:23:29 -0800 PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
When SUSE LLC hires a new member of the SUSE documentation team, what documentation tool are they allowed to use to produce the SLES documentation?
Hi Patrick,
we can to use any editor as long as it produces valid DocBook XML. This allows us to have long discussions about the old topic of vim vs. emacs :-) or just use Atom, gedit, or whatever.
However DocBook as language is set.
What is the new SUSE LLC employee provided to learn DocBook and the SUSE LLC documentation team's style in using DocBook? -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On Thu, 19 Jan 2017 16:49:56 -0800 PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <cwickert@suse.de> wrote:
On Wed, 18 Jan 2017 15:23:29 -0800 PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
When SUSE LLC hires a new member of the SUSE documentation team, what documentation tool are they allowed to use to produce the SLES documentation?
Hi Patrick,
we can to use any editor as long as it produces valid DocBook XML. This allows us to have long discussions about the old topic of vim vs. emacs :-) or just use Atom, gedit, or whatever.
However DocBook as language is set.
What is the new SUSE LLC employee provided to learn DocBook and the SUSE LLC documentation team's style in using DocBook?
Hi Patrick, that's a good question, because it reminds me of some resources I forgot to mention earlier. :-( Before I joined SUSE, I worked at Kolab Systems. The documentation for the Kolab Groupware Server was (but no longer is) written in DocBook, too. So I already knew some bits, but my knowledge was *very* limited. After almost 10 months at SUSE, I still consider my DocBook skills limited compared to my colleagues. The first thing I was given to read when I joined SUSE was the DAPS user guide [1]. I not only read it but provided feedback and fixed errors I found during reading. Next I read the SUSE Documentation Style Guide [2]. It's a collection of Dos and Don'ts compiled by the SUSE documentation team. You don't need to know it by heart, because there still is the style-checker [3] that should catch the most common things from the style guide. Neither at Kolab Systems nor at SUSE I received any DocBook training. If you know XML, the DocBook structure is self-explaining. For the elements, you need a reference such as "DocBook: The definitive Guide" [4]. Just as there are plenty of resources for DocBook, there are resources for MediaWiki [5]. For the openSUSE wiki, we have a set of Maintenance Guidelines [6]. I'm sure you know all this already. I apologize for preaching to the choir, the point I'm trying to make is the same as in my previous mail: We should not duplicate information and work. We don't need documentation for MediaWiki or DocBook, because it's already out there on the web. We should focus on the openSUSE-specific bits such as the documentation README [7], the style guide, and the wik maintenance guidelines. We should work on improving documentation for new contributors. Whatever they need to get going, we should provide it. The SUSE documentation has a lot of experience with this. We are not only responsible for the SUSE/openSUSE documentation but also for the new hires documentation within SUSE. Just as I want every new colleague to find their way into company, I want every volunteer to find their way into the community. So if you can think of ways to improve the onboarding experience for new contributors, just let us know and we will look what we can do about it. Best regards, Christoph P.S.: Again, this call for feedback goes out to all of you, not just to Patrick. :-) [1] https://opensuse.github.io/daps/doc/index.html [2] https://doc.opensuse.org/documentation/styleguide/ [3] https://github.com/openSUSE/suse-doc-style-checker/ [4] http://tdg.docbook.org/ [5] https://www.mediawiki.org/wiki/Help:Contents [6] https://en.opensuse.org/Help:Maintenance [7] https://github.com/SUSE/doc-sle/blob/develop/README.adoc -- Christoph Wickert <cwickert@suse.de> Technical Writer SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nürnberg Tel: +49-911-74053-0; Fax: +49-911-7417755; https://www.suse.com/ SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
On 2017-01-20 09:48, Christoph Wickert wrote:
On Thu, 19 Jan 2017 16:49:56 -0800 PatrickD Garvey <> wrote:
What is the new SUSE LLC employee provided to learn DocBook and the SUSE LLC documentation team's style in using DocBook?
Hi Patrick,
that's a good question, because it reminds me of some resources I forgot to mention earlier. :-(
Before I joined SUSE, I worked at Kolab Systems. The documentation for the Kolab Groupware Server was (but no longer is) written in DocBook, too. So I already knew some bits, but my knowledge was *very* limited. After almost 10 months at SUSE, I still consider my DocBook skills limited compared to my colleagues.
The first thing I was given to read when I joined SUSE was the DAPS user guide [1]. I not only read it but provided feedback and fixed errors I found during reading.
I have a curiosity. How about using LyX? As I remember, it includes docbook support, and it is WYMIWYG (what you mean is what you get). There is some visual indication of how the document is going to look (not fully). -- Cheers / Saludos, Carlos E. R. (from 42.2 x86_64 "Malachite" at Telcontar)
Hi Carlos,
Gesendet: Freitag, 20. Januar 2017 um 12:02 Uhr Von: "Carlos E. R." <robin.listas@telefonica.net> An: opensuse-wiki@opensuse.org Betreff: Re: [opensuse-wiki] Why is this acceptable?
On 2017-01-20 09:48, Christoph Wickert wrote:
On Thu, 19 Jan 2017 16:49:56 -0800 PatrickD Garvey <> wrote:
What is the new SUSE LLC employee provided to learn DocBook and the SUSE LLC documentation team's style in using DocBook?
Hi Patrick,
that's a good question, because it reminds me of some resources I forgot to mention earlier. :-(
Before I joined SUSE, I worked at Kolab Systems. The documentation for the Kolab Groupware Server was (but no longer is) written in DocBook, too. So I already knew some bits, but my knowledge was *very* limited. After almost 10 months at SUSE, I still consider my DocBook skills limited compared to my colleagues.
The first thing I was given to read when I joined SUSE was the DAPS user guide [1]. I not only read it but provided feedback and fixed errors I found during reading.
I have a curiosity.
How about using LyX? As I remember, it includes docbook support, and it is WYMIWYG (what you mean is what you get). There is some visual indication of how the document is going to look (not fully).
-- Cheers / Saludos,
Carlos E. R. Do you want to combine DocBook and wiki? Tell us about your reasons and background. But it sounds for me like Christian's proposal with the wiki plugin: https://www.mediawiki.org/wiki/Talk:WYSIWYG_editor
Best regards, Sarah -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On 2017-01-20 17:03, Sarah Julia Kriesch wrote:
Hi Carlos,
I have a curiosity.
How about using LyX? As I remember, it includes docbook support, and it is WYMIWYG (what you mean is what you get). There is some visual indication of how the document is going to look (not fully).
Do you want to combine DocBook and wiki? Tell us about your reasons and background. But it sounds for me like Christian's proposal with the wiki plugin: https://www.mediawiki.org/wiki/Talk:WYSIWYG_editor
Huh, no, I had not considered DocBook and wiki, no. If Christian proposal works that will be interesting :-) -- Cheers / Saludos, Carlos E. R. (from 42.2 x86_64 "Malachite" at Telcontar)
On Fri, 20 Jan 2017 12:02:06 +0100 "Carlos E. R." <robin.listas@telefonica.net> wrote:
How about using LyX? As I remember, it includes docbook support, and it is WYMIWYG (what you mean is what you get). There is some visual indication of how the document is going to look (not fully).
Frankly speaking I have no experience with Lyx. AFAIK it more or less usable, but not really "what you get" as all the editing happens in the lyx format and only exports to DocBook. If you really want to consistently get what you mean throughout all formats, you have to stick to the source, that means to DocBook. Also, I'm not sure if lyx supports custom schemas such as geekodoc, but it's probably a good start for somebody who is not familiar with DocBook. So if somebody wants to contribute to the SUSE/openSUSE documentation and submits something as Lxy-generated DocBook, that's perfectly fine. If it doesn't validate with our schema, a little sed and awk magic should help. Long story short: If you want to help us with the documentation and have written something, any format should do. Throw plain text at us and we will take care of the rest. We even had submissions from partners as MS Word documents, so it can't get any worse than that. ;-) Best regards, Christoph -- Christoph Wickert <cwickert@suse.de> Technical Writer SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nürnberg Tel: +49-911-74053-0; Fax: +49-911-7417755; https://www.suse.com/ SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
On 2017-01-20 18:08, Christoph Wickert wrote:
On Fri, 20 Jan 2017 12:02:06 +0100 "Carlos E. R." <robin.listas@telefonica.net> wrote:
How about using LyX? As I remember, it includes docbook support, and it is WYMIWYG (what you mean is what you get). There is some visual indication of how the document is going to look (not fully).
Frankly speaking I have no experience with Lyx. AFAIK it more or less usable, but not really "what you get" as all the editing happens in the lyx format and only exports to DocBook. If you really want to consistently get what you mean throughout all formats, you have to stick to the source, that means to DocBook.
In any case, with LyX you have to compile or create the output format. Normally it would be PDF, ps, html... In this case, there may an extra step in generating xml. The advantage of LyX is using a nice looking original that looks similar to the expected output, before "compilation". Easier to start. However... always something seems to fail.
Also, I'm not sure if lyx supports custom schemas such as geekodoc, but it's probably a good start for somebody who is not familiar with DocBook. So if somebody wants to contribute to the SUSE/openSUSE documentation and submits something as Lxy-generated DocBook, that's perfectly fine. If it doesn't validate with our schema, a little sed and awk magic should help.
I asked because years ago I tried a go with LyX and docbook, and I did not succeed. I wanted to try that method because I find the act of editing or writing in LyX easy. My goal at the time was producing man pages. Or rather translating them. I do not like having to edit and see to tokens or xml in the text, too confusing for me. I also tried with the older linuxdoc, and failed, too. The man page stylesheet (or whatever is the proper name for LyX) was incomplete or bad.
Long story short: If you want to help us with the documentation and have written something, any format should do. Throw plain text at us and we will take care of the rest. We even had submissions from partners as MS Word documents, so it can't get any worse than that. ;-)
Good to know :-) No, I do not have anything to write about currently, not for doc.opensuse. I'm just exploring possibilities. You people know more about this than me, so I took the chance to ask ;-) I do have pending work to do on the wiki, yes (the offline upgrade page). -- Cheers / Saludos, Carlos E. R. (from 42.2 x86_64 "Malachite" at Telcontar)
On Fri, Jan 20, 2017 at 12:48 AM, Christoph Wickert <cwickert@suse.de> wrote:
On Thu, 19 Jan 2017 16:49:56 -0800 PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <cwickert@suse.de> wrote:
On Wed, 18 Jan 2017 15:23:29 -0800 PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
When SUSE LLC hires a new member of the SUSE documentation team, what documentation tool are they allowed to use to produce the SLES documentation?
Hi Patrick,
we can to use any editor as long as it produces valid DocBook XML. This allows us to have long discussions about the old topic of vim vs. emacs :-) or just use Atom, gedit, or whatever.
However DocBook as language is set.
What is the new SUSE LLC employee provided to learn DocBook and the SUSE LLC documentation team's style in using DocBook?
Hi Patrick,
that's a good question, because it reminds me of some resources I forgot to mention earlier. :-(
Before I joined SUSE, I worked at Kolab Systems. The documentation for the Kolab Groupware Server was (but no longer is) written in DocBook, too. So I already knew some bits, but my knowledge was *very* limited. After almost 10 months at SUSE, I still consider my DocBook skills limited compared to my colleagues.
The first thing I was given to read when I joined SUSE was the DAPS user guide [1]. I not only read it but provided feedback and fixed errors I found during reading.
Next I read the SUSE Documentation Style Guide [2]. It's a collection of Dos and Don'ts compiled by the SUSE documentation team. You don't need to know it by heart, because there still is the style-checker [3] that should catch the most common things from the style guide.
Neither at Kolab Systems nor at SUSE I received any DocBook training. If you know XML, the DocBook structure is self-explaining. For the elements, you need a reference such as "DocBook: The definitive Guide" [4].
Just as there are plenty of resources for DocBook, there are resources for MediaWiki [5]. For the openSUSE wiki, we have a set of Maintenance Guidelines [6].
I'm sure you know all this already. I apologize for preaching to the choir, the point I'm trying to make is the same as in my previous mail: We should not duplicate information and work. We don't need documentation for MediaWiki or DocBook, because it's already out there on the web. We should focus on the openSUSE-specific bits such as the documentation README [7], the style guide, and the wik maintenance guidelines. We should work on improving documentation for new contributors. Whatever they need to get going, we should provide it.
The SUSE documentation has a lot of experience with this. We are not only responsible for the SUSE/openSUSE documentation but also for the new hires documentation within SUSE. Just as I want every new colleague to find their way into company, I want every volunteer to find their way into the community. So if you can think of ways to improve the onboarding experience for new contributors, just let us know and we will look what we can do about it.
Best regards, Christoph
P.S.: Again, this call for feedback goes out to all of you, not just to Patrick. :-)
[1] https://opensuse.github.io/daps/doc/index.html [2] https://doc.opensuse.org/documentation/styleguide/ [3] https://github.com/openSUSE/suse-doc-style-checker/ [4] http://tdg.docbook.org/ [5] https://www.mediawiki.org/wiki/Help:Contents [6] https://en.opensuse.org/Help:Maintenance [7] https://github.com/SUSE/doc-sle/blob/develop/README.adoc
-- Christoph Wickert <cwickert@suse.de> Technical Writer SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nürnberg Tel: +49-911-74053-0; Fax: +49-911-7417755; https://www.suse.com/ SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
Thank you, Christoph, for your complete answers and your patience in providing them. You say, "I'm sure you know all this already." That's a bad working assumption. It's good in that it means you respect my intelligence, but it leaves me without the complete set of information you have provided here. I first became interested in openSUSE when I saw a presentation about openQA at SCaLE 13x in 2015. I'm still, two years later, trying to understand the project work flow. I would really like to shorten that two years for those that come behind me. -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
On Fri, 20 Jan 2017 15:10:03 -0800 PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
Thank you, Christoph, for your complete answers and your patience in providing them.
Hi Patrick, no problem, you–and all the others–are welcome.
You say, "I'm sure you know all this already." That's a bad working assumption. It's good in that it means you respect my intelligence, but it leaves me without the complete set of information you have provided here.
Sorry, my bad. Even though I wrote "all this", I meant to refer only to the wiki maintenance guidelines because I assumed people on this list know them. I was not referring to all the other stuff I wrote and which is probably new to everybody but me. That's why explain it in great detail. If somebody has any questions, please don't hesitate to ask.
I first became interested in openSUSE when I saw a presentation about openQA at SCaLE 13x in 2015. I'm still, two years later, trying to understand the project work flow. I would really like to shorten that two years for those that come behind me.
That's a very noble goal, that I can wholeheartedly support. As someone who has been around in the Fedora community for over a decade, I still find many things about openSUSE confusing. Getting new contributors onboarded quickly is definitely something we should focus on when we improve the wiki. Something like a "New Contributors Guide" would be pretty cool to have. Anybody (with more experience than me) wants to work on that? I would offer being the guinea pig and ask all the questions newbies have. ;-) Best regards, Christoph -- Christoph Wickert <cwickert@suse.de> Technical Writer SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nürnberg Tel: +49-911-74053-0; Fax: +49-911-7417755; https://www.suse.com/ SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
Hello, Am Mittwoch, 25. Januar 2017, 14:10:16 CET schrieb Christoph Wickert:
That's a very noble goal, that I can wholeheartedly support. As someone who has been around in the Fedora community for over a decade, I still find many things about openSUSE confusing.
Can you please list these confusing things? I'm probably routine-blinded and don't notice them anymore ;-) [1]
Getting new contributors onboarded quickly is definitely something we should focus on when we improve the wiki.
Something like a "New Contributors Guide" would be pretty cool to have. Anybody (with more experience than me) wants to work on that? I would offer being the guinea pig and ask all the questions newbies have. ;-)
Wrong attemp - someone with more experience can't write such a guide ;-) I'd write the "New Contributors Guide" in one sentence - "just do it!". While this is IMHO the most important thing to learn in openSUSE (actually in any open source project), it probably isn't too helpful for new contributors. Again, I'm probably routine-blinded ;-) Therefore I'd propose that _you_ start to write this guide. You already have a bit of experience, but are not as routine-blinded as I might be, and probably remember which of your first steps were most difficult. Also, while writing the guide, you'll find out which questions are easy to answer (so you just need to link to the respective wiki page etc.) and which are hard to answer (which means missing or hard to find information). If you can't answer a question yourself, feel free to ask on the mailinglist. I'll also be available to proofread if whatever you write makes sense or if it needs adjustments. So - did I already mention that you should "just do it" without being afraid of mistakes? [2] Regards, Christian Boltz [1] Just to give you an idea - I use SuSE Linux since 7.3 (IIRC), and became a betatester in 9.2 after asking and answering too many questions on the suse-linux (nowadays opensuse-de) mailinglist. [2] Mistakes are a good thing because you learn something from them ;-) --
I can do better things with my life and free time then to just scroll up and down on a mailing list. Come on, let's not be childish! That's where the children come from: scrolling up and down with your wife. [>> houghi, > Christoph Thiel and Eberhard Moenkeberg in opensuse]
-- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org
participants (7)
-
Adam Spiers -
Ancor Gonzalez Sosa -
Carlos E. R. -
Christian Boltz -
Christoph Wickert -
PatrickD Garvey -
Sarah Julia Kriesch