[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-devel
Subject: Re: KDE Developer Documentation
From: Olivier Churlaud <olivier () churlaud ! com>
Date: 2019-12-28 0:34:09
Message-ID: 9C75A266-6688-46D2-910E-2A22D4244A28 () churlaud ! com
[Download RAW message or body]
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@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@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é.
[Attachment #3 (text/html)]
<html><head></head><body>Hi,<br><br>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.<br><br>Sebastian Klüger was the one who raised the idea. I \
have no idea if something came out of this.<br><br>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. \
<br><br>Best regards,<br>Olivier <br><br><div class="gmail_quote">Le 27 décembre \
2019 14:22:16 GMT+01:00, Juan Carlos Torres <jucato@kdemail.net> a écrit \
:<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px \
solid rgb(204, 204, 204); padding-left: 1ex;"> <div dir="ltr">Hi \
Olivier,<div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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).</div><div><br></div><div>Any guidance on the matter is \
much appreciated!</div><div><br></div><div>[1] <a \
href="https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html">https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html</a></div></div><br><div \
class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Dec 24, 2019 at 9:17 PM \
Olivier Churlaud <<a href="mailto:ochurlaud@sfr.fr">ochurlaud@sfr.fr</a>> \
wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi all (and especially \
Juan Carlos), <br> <br>
I just read your report and it's very interesting. I agree with most of what you \
wrote.<br> <br>
I have some minor precisions to give about Techbase:<br>
<br>
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.<br> <br>
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 <a href="http://api.kde.org" rel="noreferrer" \
target="_blank">api.kde.org</a> 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.<br> <br>
Except of this small remark, I really think you did an awesome job of synthesis \
that will be valuable for priorizing the work ahead.<br> <br>
Best regards<br>
Olivier<br>
<br>
[1] <a href="https://phabricator.kde.org/D14955" rel="noreferrer" \
target="_blank">https://phabricator.kde.org/D14955</a><br> [2] <a \
href="https://phabricator.kde.org/D14957" rel="noreferrer" \
target="_blank">https://phabricator.kde.org/D14957</a><br> <br>
Le lundi 23 décembre 2019, 12:00:43 CET Juan Carlos Torres a écrit :<br>
> Greetings KDE developers and community members!<br>
> <br>
> In March this year, we started on a journey to take stock of our developer<br>
> documentation and what needs to be done to make them not only more helpful<br>
> to current contributors but also more inviting to new ones as well as<br>
> external users of frameworks.<br>
> <br>
> The formal work ended in June and I submitted a full report [1] that<br>
> included an analysis of the current state of developer documentation as<br>
> well as the proposed actions the community could take together in the<br>
> months and years ahead. Unfortunately, due to personal and family<br>
> circumstances, I was unable to follow the matter up and for that, I am<br>
> truly sorry.<br>
> <br>
> Six months have passed since then and while the initial report still holds<br>
> true, events and situations have opened new opportunities for the community<br>
> to focus on. An updated report [2] was submitted to the e.V. reflecting<br>
> these small but important changes. Here is a brief summary of the points in<br>
> the reports.<br>
> <br>
> 1. With Qt 6 and KDE Frameworks 6 underway, it is both all the more<br>
> important and also a perfect opportunity to update our API documentation<br>
> and make sure that they are complete and in good quality.<br>
> <br>
> 2. There is a growing interest in mobile devices and convergent experiences<br>
> which is a good chance to attract more developers into Kirigami and Plasma<br>
> Mobile. Updating the developer documentation and documentation systems for<br>
> these two projects will be important.<br>
> <br>
> 3. While still important in order to maintain an orderly environment,<br>
> cleaning up and organizing the wikis now takes a lower priority. That said,<br>
> certain aspects like guides for new contributors and external developers<br>
> are just as or even more important now than ever.<br>
> <br>
> 4. Since many parts of the developer documentation, particularly those<br>
> related to Frameworks, might be in a period of transition or rapid change,<br>
> it might be more practical to focus on creating content first in a<br>
> temporary staging ground before having writers deal with different systems<br>
> and software. The Wikis are perhaps suited for this kind of workflow.<br>
> <br>
> These are just some of the high-level points from the two reports and those<br>
> documents contain more precise suggestions for the next actions to take.<br>
> Again, I apologize to the community for dropping the ball for so long and I<br>
> am very excited to get it rolling again. Let's make KDE and its developer<br>
> documentation rock even more!<br>
> <br>
> Attached files:<br>
> <br>
> 1. 01 KDE Developer Documentation Update Project Report.pdf<br>
> 2. 02 KDE Developer Documentation Report Update - 2019-12-09.pdf<br>
> <br>
> <br>
<br>
<br>
<br>
<br>
</blockquote></div><br clear="all"><div><br></div>-- <br><div dir="ltr" \
class="gmail_signature">Regards,<br><br>Juan Carlos Torres<br>Jucato<br></div> \
</blockquote></div><br>-- <br>Envoyé de mon appareil Android avec Courriel K-9 Mail. \
Veuillez excuser ma brièveté.</body></html>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic