Revisiting the TechBase situation (2 proposals)

[Juan Carlos Torres]

On Wed, Apr 3, 2019 at 12:53 AM Friedrich W. H. Kossebau <kossebau at kde.org>
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-www/attachments/20190403/383efb63/attachment-0001.html>