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)