On Thu, 19 Jan 2017 16:49:56 -0800
PatrickD Garvey
On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert
wrote: On Wed, 18 Jan 2017 15:23:29 -0800 PatrickD Garvey
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