Revisiting the TechBase situation (2 proposals)

[Friedrich W. H. Kossebau]

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