<div dir="ltr"><div dir="ltr">On Wed, Apr 3, 2019 at 12:53 AM Friedrich W. H. Kossebau <<a href="mailto:kossebau@kde.org">kossebau@kde.org</a>> wrote:<br></div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi Juan,<br>
<br>I do not think I can agree here.<br></blockquote><div><br></div><div>Thank you very much for your valuable feedback! It's exactly why I put out</div><div>the email, not to push for a final decision yet but to gather developers' insight</div><div>and experiences.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Let's look at 3rd-party libraries like Qt or developer tools one uses. Would <br>you prefer to have documentation of the libraries and tools concentrating on <br>the usage, or documentation mixed and blown-up with producing-community-<br>internal stuff?<br></blockquote><div><br></div><div>I think KDE is in a rather unique position compared to those other tools both in size</div><div>and in scope so it's hard to draw parallels. In most cases, projects like Qt and Gnome have</div><div>distinct documentation sites different from their wikis (and in Qt's case, the community-driven</div><div>wiki is pretty much independent of what goes on inside Qt). </div><div><br></div><div>But yes, I do see your point. There is a line that divides the documentation for using </div><div>the tools//libraries and community-internal information. Sometimes, though, that line isn't always</div><div>clear. Should documentation on how to develop Plasmoids be on TechBase or on Community?</div><div>That, however, might be a special case given Plasma's nature, but we might have other</div><div>special cases as well.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Yes, KDE projects could see more contributors. But that goal needs to be <br>balanced with the goal to make KDE's developer-targeted products usable.<br>And bloated documentation with out-of-scope information is unattractive.<br></blockquote><div><br></div><div>I definitely agree, which is one of the cons for merging the docs. But it also doesn't have</div><div>to be visibly bloated if structured and organized properly. Then again, split or merged,</div><div>our docs should be organized properly anyway. :)</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">From comparison, I very much think that having an explicit place for external <br>developers who simply want to use the products shared with them to get their <br>job done, but not distracted by "community" stuff is better. It should also <br>make sure the documentation is self-consistent, not assuming knowledge only <br>available to KDE contributors/community.<br></blockquote><div><br></div><div>They shouldn't have to. They could just be presented with a link to the stuff they need.</div><div>Again, it could be done with organization and presentation. They don't and shouldn't have</div><div>to wade through "how to build frameworks from source" just to get to "how to use</div><div>KArchive", for example.</div><div>  </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">You said "On paper" things are clear. But for what is put in comparison, I am <br>missing here some deeper non-paper real world analysis and research, talking <br>about project goals confronted with feedback from stakeholders.<br>Do we e.g. have stories collected from 3rd-party developers? What do non-KDE <br>people say who tried to use KArchive? Or Kirigami? Or Marble libraries?<br>
<br>Any chance we could have an example of a library here and collect the <br>different developer and contributor stories, to see how documentation could <br>be best organized for them? </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>In your current proposals, IMHO you are also very focussed on the artifacts <br>of the current two wiki installations. Can't we have a greater plan here?<br>What about the development of the documentation (incl. translations), did the <br>random access wiki approach work? Would we rather need properly authored <br>documentation writing, with a clear plan and structure and official <br>maintainers/supervisors, including "releases"? <br>How to prevent outdated information, how to provide information for multiple <br>versions of a product in use out there, how to provide updated information at <br>the time of release of a new product variant?<br>Has perhaps the central wiki idea not worked out, would perhaps separate <br>projects also need distinct separate areas for documentation? And dedicated <br>teams, at least some dedicated organisation center? What types of <br>information/documentation is there at all?<br></blockquote><div><br></div><div>That is definitely the end goal here (as far as the documentation job is concerned),</div><div>to have a greater plan. The wikis are just one part of that (the apidocs are another,</div><div>which I had a different email for) but rather than just dumping something at the end</div><div>of three months out of the blue, I've also started reaching out to the community</div><div>with the notes and proposals I have so far (release early, release often ...). </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Changing things once more based on opinions (this is what for now the <br>statements appear to me, incl. mine) will just result in changes back and <br>forth, driven randomly by those "who do the work" or have the time/resources <br>to do so. That way KDE will stay where it got stuck in the last years.<br></blockquote><div><br></div><div>I put out this email (as well as the other ones before it) exactly to solicit feedback</div><div>from those who have been in the front lines. I'm hoping more will chime in. When I</div><div>started going over them a few weeks ago, there are still some things that seem to be</div><div>stuck in transition. Whether that means the split wikis strategy was a problem, I'd like</div><div>to hear from those who do the work.</div><div><br></div><div>But, yes, whether we stick to two wikis or one, it has to be something that we'll stick to</div><div>for years to come. Which is also why we need to have a sustainable strategy as well.</div><div><br></div><div>Again, thank you for spending the time in replying with your perspective.</div><div><br></div><div><br></div></div>-- <br><div dir="ltr" class="gmail_signature">Regards,<br><br>Juan Carlos Torres<br>Jucato<br></div></div>