Mailinglist Archive: opensuse-doc (14 mails)

< Previous Next >
[opensuse-doc] Re: [opensuse-project] doc.opensuse.org
(Adding the opensuse docs ML to cc)

On 15/10/2019 22:46, Jason Evans wrote:
if we're building up on the existing documentation contributed by
SUSE
folks.
Actually I'm talking about creating new documents and not just putting
in pull requests for the existing docs. For example, besides the quick
start guide that I wrote last spring there isn't much for Kubic. I
think we need a new document build from scratch on how to use it.
The repo is open, so if you think a new document is required, then go right
ahead.
I've been looking at Docbook the past few days in order to contribute
somehow on Container documentation. I think Docbook's fine,
especially


Having part of the documentation written in Docbook and another part
in
AsciiDoc leads to the same as having doc.o.o vs wiki.o.o.
Actually the SUSE docs team does that now. Daps natively handles both.
Some people only write in Docbook and some only write in asciidoc. You
can't tell the difference because Daps produces the same output for
both.
That is true. If you're editing existing docbook content, then use docbook. Of
course, if you want to create a new document, feel free to use asciidoc. The
use of asciidoc is still fairly new within the team, so there are fewer
guidelines, etc, written down, but that is improving. I have used both
languages extensively, so I'm always here to help if you have questions on
syntax or usage.

I think the goal would be to encourage community participation. Docbook
creates an artificial roadblock to that because of it's significantly
higher learning curve. We should want people spending their valuable
time submitting pull requests to help build something not spending
hours trying to find out why their xml isn't working.

I agree with you on this. I've worked on a few community docs teams that
switched from heavier languages like docbook to markup languages, and there's
always a corresponding increase in outside contributions after the change.

Thanks for your interest :)


Lana


--
Lana Brindley
@Loquacities
Technical Writer - SUSE Manager

"The question is," said Alice, "whether you
can make words mean so many different things."


--
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: opensuse-doc+owner@xxxxxxxxxxxx

< Previous Next >
List Navigation
This Thread
  • No further messages