On Thu, Dec 29, 2016 at 12:40 AM, Ancor Gonzalez Sosa <ancor@suse.de> wrote:
On 12/28/2016 03:10 AM, PatrickD Garvey wrote:
I do not understand decisions such as documented in https://en.opensuse.org/Icecream, "The documentation used to live in this page, but moved into a markdown README hosted under https://github.com/icecc/icecream. To report an issue or fix a problem, use github. You can fork the repo to edit the README.md just fine."
First of all, this is the first time I hear about Icecream and I don't know the developers. That been said, I perfectly understand they moved the documentation to Github.
1) Github is the platform where the real development of Icecream happens. It's simply natural for developers to use the same mechanisms (pull requests) and platform to maintain the documentation.
2) On the other hand, almost everybody on the open source (and/or free software) universe is using Github nowadays. Everybody who is in the position to help (developers and users) is used to Github and, most likely, has an account there. You don't need an openSUSE account to contribute documentation.
3) The content in Github is way more visible than the one at our wiki. The openSUSE wiki is kind of a niche that only we use (and that we are using less and less, IMHO). Try to search something in Google (or any other popular search engine) that is both in Github and in our wiki. The first one will be found and in a high position, for the latter I'm not so sure.
In short, IMHO Github is the natural choice to keep the documentation of a software project. We shouldn't be surprised if people moves away from the openSUSE wiki for that purpose.
Cheers. -- Ancor González Sosa YaST Team at SUSE Linux GmbH
OK, I thought that would be the basic direction of an answer, but the openSUSE wiki article claims icecream is a SUSE LLC employee created program. Doesn't it lose that identity when it is hosted on GitHub.com? Shouldn't it be hosted on GitLab.SUSE.de? That is, to become an official SUSE product, it could be developed on GitHub if an individual so chose, but it would not be official until that individual issued a pull request and it was accepted. And, then there is the challenge of learning a new syntax to do an existing task. This makes the third syntax I've seen used in writing *SUSE documentation. Doc.openSUSE.org requires one to know how to use a proprietary variant of Docbook. En.openSUSE.org requires knowledge of WikiMediA syntax. And icecream is written in Markdown. And let's not leave out the desire to make this documentation available to an international audience. I'm not a translator, so I'm not that familiar with how many syntactical structures are required across the documentation variants, but I've seen emotional discussions when someone proposes a change in the translation workflow. All these "solutions" break the *SUSE community into smaller and smaller cooperative groups and increase the cost of producing a quality offering. That's the frustration generator for me. Respectfully, PatrickD -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org