KDE Developer Documentation

[Olivier Churlaud]

Hi,

At CERN we didn't speak about this, except with the Plasma team who spoke about having a cookbook based on git containing all the code and explanations.

Sebastian Klüger was the one who raised the idea. I have no idea if something came out of this.

For frameworks we wanted to break the idea that you need to take all kf5 libs to use one, hence we didn't want to promote too much the transverse tutorial. This idea can be challenged, though. 

Best regards,
Olivier 

Le 27 décembre 2019 14:22:16 GMT+01:00, Juan Carlos Torres <jucato at kdemail.net> a écrit :
>Hi Olivier,
>
>Thank you for the compliments and the pointers! Having the example code
>in
>the git repo is definitely a great idea to make sure they will always
>compile. In line with that, we also need to make sure that each
>framework
>has such an example program that serves as an introduction to that
>framework. That will be part of the work to update and create more
>content
>for the API docs.
>
>I'm not sure it will be sufficient to address a different kind of
>documentation, one that goes across specific APIs. I'm talking about
>tutorials on getting started that use different frameworks, or
>tutorials
>for other KDE software and components that don't neatly fit into the
>apidocs (at least afaik). The Qt docs are full of such tutorials (like
>[1]
>for starters) that live alongside the apidocs.
>
>Was there any discussion on where such developer documentation would
>live
>other than the wiki? I was not at CERN so I'm afraid I'm not up-to-date
>in
>that matter. If they should live in the wikis, we're back to the
>problem of
>figuring out a way to keep the code and the content from rotting. If it
>were possible to have the code live in Git and then embedded in the
>wiki,
>that would at least solve half the problem (there are MediaWiki plugins
>but
>I think they are deemed unsafe).
>
>Any guidance on the matter is much appreciated!
>
>[1] https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html
>
>On Tue, Dec 24, 2019 at 9:17 PM Olivier Churlaud <ochurlaud at sfr.fr>
>wrote:
>
>> Hi all (and especially Juan Carlos),
>>
>> I just read your report and it's very interesting. I agree with most
>of
>> what you wrote.
>>
>> I have some minor precisions to give about Techbase:
>>
>>  The goal was to remove (or only archive) the tutorials on techbase
>and
>> replace them by examples within the framework.   If having tutorials
>on a
>> wiki is nice and findable, it is obsolete very soon after being
>written and
>> we lack the resources for keeping an eye on every KDE library to
>curate and
>> update the tutorial.
>>
>> The conclusion of that was that tutorials need to live next to the
>> frameworks they belong to AND that they break the compilation if they
>are
>> out of date. I did some examples [1] and [2].It's a lot of work to do
>that,
>> though, but at least it stays up to date. It could be loaded in
>> api.kde.org in the future with snippets. That is basically what you
>> propose, issue is that it was never finished. Pruning Techbase would
>really
>> help as well. Porting the KDE4 Tutorials to KF5 in the wiki doesn't
>seem to
>> me like the best idea because it's just moving the problem to the
>future.
>>
>> Except of this small remark,  I really think you did an awesome job
>of
>> synthesis that will be valuable for priorizing the work ahead.
>>
>> Best regards
>> Olivier
>>
>> [1] https://phabricator.kde.org/D14955
>> [2] https://phabricator.kde.org/D14957
>>
>> Le lundi 23 décembre 2019, 12:00:43 CET Juan Carlos Torres a écrit :
>> > Greetings KDE developers and community members!
>> >
>> > In March this year, we started on a journey to take stock of our
>> developer
>> > documentation and what needs to be done to make them not only more
>> helpful
>> > to current contributors but also more inviting to new ones as well
>as
>> > external users of frameworks.
>> >
>> > The formal work ended in June and I submitted a full report [1]
>that
>> > included an analysis of the current state of developer
>documentation as
>> > well as the proposed actions the community could take together in
>the
>> > months and years ahead. Unfortunately, due to personal and family
>> > circumstances, I was unable to follow the matter up and for that, I
>am
>> > truly sorry.
>> >
>> > Six months have passed since then and while the initial report
>still
>> holds
>> > true, events and situations have opened new opportunities for the
>> community
>> > to focus on. An updated report [2] was submitted to the e.V.
>reflecting
>> > these small but important changes. Here is a brief summary of the
>points
>> in
>> > the reports.
>> >
>> > 1. With Qt 6 and KDE Frameworks 6 underway, it is both all the more
>> > important and also a perfect opportunity to update our API
>documentation
>> > and make sure that they are complete and in good quality.
>> >
>> > 2. There is a growing interest in mobile devices and convergent
>> experiences
>> > which is a good chance to attract more developers into Kirigami and
>> Plasma
>> > Mobile. Updating the developer documentation and documentation
>systems
>> for
>> > these two projects will be important.
>> >
>> > 3. While still important in order to maintain an orderly
>environment,
>> > cleaning up and organizing the wikis now takes a lower priority.
>That
>> said,
>> > certain aspects like guides for new contributors and external
>developers
>> > are just as or even more important now than ever.
>> >
>> > 4. Since many parts of the developer documentation, particularly
>those
>> > related to Frameworks, might be in a period of transition or rapid
>> change,
>> > it might be more practical to focus on creating content first in a
>> > temporary staging ground before having writers deal with different
>> systems
>> > and software. The Wikis are perhaps suited for this kind of
>workflow.
>> >
>> > These are just some of the high-level points from the two reports
>and
>> those
>> > documents contain more precise suggestions for the next actions to
>take.
>> > Again, I apologize to the community for dropping the ball for so
>long
>> and I
>> > am very excited to get it rolling again. Let's make KDE and its
>developer
>> > documentation rock even more!
>> >
>> > Attached files:
>> >
>> > 1. 01 KDE Developer Documentation Update Project Report.pdf
>> > 2. 02 KDE Developer Documentation Report Update - 2019-12-09.pdf
>> >
>> >
>>
>>
>>
>>
>>
>
>-- 
>Regards,
>
>Juan Carlos Torres
>Jucato

-- 
Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-community/attachments/20191228/828e04d7/attachment.htm>