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)