(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
> 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,
>> Having part of the documentation written in Docbook and another part
>> 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
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 :)
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(a)opensuse.org
To contact the owner, e-mail: opensuse-doc+owner(a)opensuse.org