(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-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org