Web lists-archives.com

Re: Revisiting the TechBase situation (2 proposals)




On Wed, Apr 3, 2019 at 12:53 AM Friedrich W. H. Kossebau <kossebau@xxxxxxx> wrote:
Hi Juan,

I do not think I can agree here.

Thank you very much for your valuable feedback! It's exactly why I put out
the email, not to push for a final decision yet but to gather developers' insight
and experiences.
 
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?

I think KDE is in a rather unique position compared to those other tools both in size
and in scope so it's hard to draw parallels. In most cases, projects like Qt and Gnome have
distinct documentation sites different from their wikis (and in Qt's case, the community-driven
wiki is pretty much independent of what goes on inside Qt). 

But yes, I do see your point. There is a line that divides the documentation for using 
the tools//libraries and community-internal information. Sometimes, though, that line isn't always
clear. Should documentation on how to develop Plasmoids be on TechBase or on Community?
That, however, might be a special case given Plasma's nature, but we might have other
special cases as well.
 
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.

I definitely agree, which is one of the cons for merging the docs. But it also doesn't have
to be visibly bloated if structured and organized properly. Then again, split or merged,
our docs should be organized properly anyway. :)

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.

They shouldn't have to. They could just be presented with a link to the stuff they need.
Again, it could be done with organization and presentation. They don't and shouldn't have
to wade through "how to build frameworks from source" just to get to "how to use
KArchive", for example.
  
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?

That is definitely the end goal here (as far as the documentation job is concerned),
to have a greater plan. The wikis are just one part of that (the apidocs are another,
which I had a different email for) but rather than just dumping something at the end
of three months out of the blue, I've also started reaching out to the community
with the notes and proposals I have so far (release early, release often ...). 
 
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.

I put out this email (as well as the other ones before it) exactly to solicit feedback
from those who have been in the front lines. I'm hoping more will chime in. When I
started going over them a few weeks ago, there are still some things that seem to be
stuck in transition. Whether that means the split wikis strategy was a problem, I'd like
to hear from those who do the work.

But, yes, whether we stick to two wikis or one, it has to be something that we'll stick to
for years to come. Which is also why we need to have a sustainable strategy as well.

Again, thank you for spending the time in replying with your perspective.


--
Regards,

Juan Carlos Torres
Jucato