On Wed, Apr 3, 2019 at 12:53 AM Friedrich W. H. Kossebau <kosse...@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
