Revisiting the TechBase situation (2 proposals)

[Olivier Churlaud]

Hello,

Le mardi 2 avril 2019, 18:49:59 CEST Friedrich W. H. Kossebau a écrit :
> 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?
> 

I agree 100% with what Friedrich wrote, which is nice because it's exactly the line we decided back at CERN at the Wiki sprint.

The community needs a place to synchronize and deal with organization matters.
The devs who are out of KDE, as much as the one from within need an entry point to contact knowledgeable people, to get documentation and tutorials.

I clearly find a distinction here between community for the former and techbase for the latter.

This was the first step, defining the containers. Now there is a lot of work to do to improve the content. I've seen that Nate and a lot of others whose name I forgot (really sorry guys'n'gals) made changes on the onboarding parts that already improved the situation, but it is certain that it can still become better.

If it's not clear, I wouldn't do neither of your propositions, but try to find a nice frame to show outside people that they can reliabily use our software (on tech/userbase.ko), and to help potential contributors finding their way to the community (on community.ko).

Cheers,
Olivier 

> 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
> 
> 
> 
>