[opensuse-project] doc.opensuse.org
Hi all, I've been trying to catch up on this thread but it's getting a bit unwieldy. So, I want to ask a question. Currently doc.opensuse.org only contains SUSE contributed work. What needs to happen for a dedicated section to be added for user contributed work? I don't think the answer should automatically be, "put it in the wiki". The wiki is fantastic for some things but it is also chaotic and some things are hard to find. I think it would be best if we had a dedicated set of user contributed docs that can be edited in asciidoc. The source code would live in github and then regularly updated with daps to update the online versions of the docs. There really is no reason to write any user contributed docs in docbook unless someone really really wants to learn it. (see https://opensuse.github.io/daps/doc/daps-asciidoc.html). Jason
Hi Jason,
i second that. I read the documentation alot and like it in the format
it is presented. The wiki has its use but a different purpose.
The one time I added something to the documentation was via a bugzilla
entry. If there was a more direct way to contribute I would appreciate
it very much!
Greetings,
Bernd
Am Di., 15. Okt. 2019 um 09:26 Uhr schrieb Jason Evans
Hi all,
I've been trying to catch up on this thread but it's getting a bit unwieldy. So, I want to ask a question. Currently doc.opensuse.org only contains SUSE contributed work. What needs to happen for a dedicated section to be added for user contributed work?
I don't think the answer should automatically be, "put it in the wiki". The wiki is fantastic for some things but it is also chaotic and some things are hard to find.
I think it would be best if we had a dedicated set of user contributed docs that can be edited in asciidoc. The source code would live in github and then regularly updated with daps to update the online versions of the docs. There really is no reason to write any user contributed docs in docbook unless someone really really wants to learn it. (see https://opensuse.github.io/daps/doc/daps-asciidoc.html).
Jason
-- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
Hi Jason, On 10/15/19 11:24 AM, Jason Evans wrote:
I think it would be best if we had a dedicated set of user contributed docs that can be edited in asciidoc. The source code would live in github and then regularly updated with daps to update the online versions of the docs. There really is no reason to write any user contributed docs in docbook unless someone really really wants to learn it. (see https://opensuse.github.io/daps/doc/daps-asciidoc.html).
I've been looking at Docbook the past few days in order to contribute somehow on Container documentation. I think Docbook's fine, especially if we're building up on the existing documentation contributed by SUSE folks. 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. Regards, Ish Sookun -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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.
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. 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.
Regards,
Ish Sookun
-- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@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-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
participants (4)
-
Bernd Ritter -
Ish Sookun -
Jason Evans -
Lana Brindley