Hi Juan, Am Dienstag, 2. April 2019, 16:20:42 CEST schrieb Juan Carlos Torres: > Greetings, > > I won't be going into history but right now we have two developer-facing > wikis: TechBase and Community. On paper, the division between the two is > clear: "external" vs "community". In addition to still being in transition, > the distinction doesn't always work well in practice: > > - Tutorials and information for external developers (a.k.a. users of our > libraries/software) are pretty much the same tutorials new internal > developers would use. > - Readers are led to jump back and forth between the two wikis, which may > make them lose context. > - There is also a risk that documentation gets duplicated, put in the wrong > wiki, forgotten, etc. > > On the non-technical side, it also creates this "them vs us" division. Of > course, we do have hard rules on projects that get hosted on our > infrastructure as an official part of the KDE community. But putting up > that fence there might not be a good way to encourage "users of our > libraries" to eventually become part of the community and help develop > those libraries.
I do not think I can agree here. Let's look at 3rd-party libraries like Qt or developer tools one uses. Would you prefer to have documentation of the libraries and tools concentrating on the usage, or documentation mixed and blown-up with producing-community- internal stuff? And would you even have time to ever consider contributing to the development of all the things you use? So what is the ratio of content provided to content meaningful to one's needs? As a matter of fact, if we ever manage to make KDE libraries attractive to non-KDE developers, the number of users will be >> contributors. And there is a clear "they", the only-users, and a clear "us", the contributor-users. Pretending that separation does not exist only results in giving up or ignoring the only-users. And I wonder why it should be a "vs." instead of an "and"? Also inside the KDE meta-community, many developers/projects are only-users of the products of other projects under the KDE umbrella. Simply because they are already busy enough with their own project. So they are 3rd-party as well, who prefer focused documentation for a given need. Surely there should be also easy to reach links for those who need more from a product and for that want to contribute & give back or consider to do so. But contributing to a project is a completely different need, and needs a special documentation (area). Like the documentation for users is concentrating on allowing them to use the products, I see no difference to developer users for their set of products. Yes, KDE projects could see more contributors. But that goal needs to be balanced with the goal to make KDE's developer-targeted products usable. And bloated documentation with out-of-scope information is unattractive. >From comparison, I very much think that having an explicit place for external developers who simply want to use the products shared with them to get their job done, but not distracted by "community" stuff is better. It should also make sure the documentation is self-consistent, not assuming knowledge only available to KDE contributors/community. You said "On paper" things are clear. But for what is put in comparison, I am missing here some deeper non-paper real world analysis and research, talking about project goals confronted with feedback from stakeholders. Do we e.g. have stories collected from 3rd-party developers? What do non-KDE people say who tried to use KArchive? Or Kirigami? Or Marble libraries? Any chance we could have an example of a library here and collect the different developer and contributor stories, to see how documentation could be best organized for them? In your current proposals, IMHO you are also very focussed on the artifacts of the current two wiki installations. Can't we have a greater plan here? What about the development of the documentation (incl. translations), did the random access wiki approach work? Would we rather need properly authored documentation writing, with a clear plan and structure and official maintainers/supervisors, including "releases"? How to prevent outdated information, how to provide information for multiple versions of a product in use out there, how to provide updated information at the time of release of a new product variant? Has perhaps the central wiki idea not worked out, would perhaps separate projects also need distinct separate areas for documentation? And dedicated teams, at least some dedicated organisation center? What types of information/documentation is there at all? Changing things once more based on opinions (this is what for now the statements appear to me, incl. mine) will just result in changes back and forth, driven randomly by those "who do the work" or have the time/resources to do so. That way KDE will stay where it got stuck in the last years. Cheers Friedrich
