On Wed, 18 Jan 2017 15:23:29 -0800
PatrickD Garvey
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