Talk:Development/Tutorials/Programming Tutorial KDE 4: Difference between revisions

From KDE TechBase
(makefiles.am)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Moving "Getting Help"==
Getting Help/Contact belongs to the Contact / Contribute pages, not into this tutorial itself (it only bloats up the page) - what do you think? [[User:Dhaumann|Dhaumann]] 17:05, 23 December 2006 (CET)
Getting Help/Contact belongs to the Contact / Contribute pages, not into this tutorial itself (it only bloats up the page) - what do you think? [[User:Dhaumann|Dhaumann]] 17:05, 23 December 2006 (CET)


Line 6: Line 7:


:::personally i think the "finding other developers" belongs in the Getting Started area, as it's something that anyone working on a kde application would want or even need to do. the finding documentation section could perhaps be broken out into it's own little tutorial? that tutorial could cover: developer[new].kde.org, accessing api documentation online as well as locally via konqueror or kdeveloper (qt assistant?), lxr.kde.org ...?
:::personally i think the "finding other developers" belongs in the Getting Started area, as it's something that anyone working on a kde application would want or even need to do. the finding documentation section could perhaps be broken out into it's own little tutorial? that tutorial could cover: developer[new].kde.org, accessing api documentation online as well as locally via konqueror or kdeveloper (qt assistant?), lxr.kde.org ...?
:While this is being decided, I'll move the "Your lessons" section near the top. Since, to be honest, if someone clicked on the "KDE 4 Programming Tutorial" link on the [[Development/Tutorials|Tutorials]] page then they're going to be expecting tutorials, not a page full of non-tutorial txt. --[[User:Milliams|milliams]] 00:29, 4 January 2007 (CET)
:Okay, coming back to this again. This information ''needs'' to be in a easier to find place. At the moment it's the best source of information on the KDE IRC channels I can find anywhere and it needs to be more prominent. On kde.org, this sort of info is under "Getting Started" but I'm not sure where it belongs on TechBase (if at all). Perhaps some sort of Contact page or maybe it should all simply be put on kde.org? --[[User:Milliams|milliams]] 01:10, 11 March 2007 (CET)


== Breaking this out into separate tutorials? ==
== Breaking this out into separate tutorials? ==
Line 11: Line 16:
I have to say that this seems to be duplicating much of intent of the Tutorials section in general. The topics are pretty eclectic (nearly random?) and would each make nice top-level tutorials where they would be more visible and likely gain more editing love as well as readership. thoughts?
I have to say that this seems to be duplicating much of intent of the Tutorials section in general. The topics are pretty eclectic (nearly random?) and would each make nice top-level tutorials where they would be more visible and likely gain more editing love as well as readership. thoughts?


== makefiles.am ==
:I feel that this page should just be introductory tutorials about the basics of KDE4 programming. The others (like printing and sound) should be moved to the main Tutorials page. -- milliams
 
::I decided that instead of just saying 'should', I've gone ahead and written some tutorials which are aimed at developers complely new to KDE (but who know C++ (and maybe Qt)). I've also reformatted the 'First Program' tutorial to fit in with mine (to make a series of it). --milliams 22:55, 3 January 2007 (CET)
 
:::the tutorials look great. but i'm once again struck by the thought that these simply don't belong here but on the main tutorials page. tutorial #4 is about kconfigxt. we already have a tutorial on kconfigxt on the main tutorials page, and i'd suggest that is where this one belongs as well. if it's meant to be a more introductory piece than the existing one (e.g. introduces KConfig and friends, etc), then it can be placed before it (and perhaps even numbered appropriately?). if someone comes to the site asking "what does kde provide for configuration?" will they really find it all if that information is in the "beginner's tutorial" and some of that information is on the main tutorials page? and will people working on kconfig (to keep picking on that example ;) remember to update all the kconfig related tutorials spread around the tutorials area? i'm willing to help move things around on friday, but i don't want to do that without the blessings of those involved in authoring this set of rather nice tutorials... [[User:aseigo|aseigo]]
 
::::OK, agreed. My KConfig tutorial should be on the main tutorial page along with the main KConfig intro. I see two possible ways to sort out what to do with the rest: (1) This page should be renamed to something like "Introduction to KDE Programming" The three (tutorial 1-3) tutorials I wrote should stay here since they are really aimed at completely new KDE developers but all the rest should be moved to appropriate places on the main Tutorial page. (2) All the tutorials should be moved to the main tutorial page and put in sensible places but that the three (tutorial 1-3) tutorials that I wrote should be put under a new heading and names with the 101, 110 etc. naming scheme. --[[User:Milliams|milliams]] 14:06, 4 January 2007 (CET)
 
::::What I really think would work well is something like what the Qt documentation has at [http://doc.trolltech.com/4.2/examples.html Qt 4.2: Qt Examples]. Here they've written a series of tutorials (the one that build up an application, introducing one concept at a time) and then, after that, have got a largish number of 'examples' where they show you how to use a specific technology/widget/concept. The latter, I feel, is covered by the tutorials on the main tutorial page (i18n/solid/dbus etc.) but I do think we need a simple introductory tutorial which walks the new developer through KDE programming which is what I feel this page should aim for. --[[User:Milliams|milliams]] 14:06, 4 January 2007 (CET)
 
::::: i agree that we need a basic "getting started" tutorial; i also think your efforts here are doing a great job providing exactly that. i also agree that the tutorials on the main page should serve a similar purpose to Qt's examples (though hopefully we can structure it a bit better even). perhaps instead of covering kconfigxt in tutorial 4, you could cover "just" kconfig itself? that seems like a basic introductory concept. and then point from there to the article on kconfig xt (which adds all the xml stuff to the mix). kapplication, mainwindow, actions, config .. those are pretty universal concepts. most everything else varies from app to app based on needs/scope/audience of the app imho. so ... sounds like we're at an agreement point here? --[[User:Aseigo|Aseigo]] 22:02, 4 January 2007 (CET)
 
:::: Just a quick sidenote: I think it's bad to have 10 tutorials of the same thing (a bit exaggerated =). Let's try to have only one. And if we need more advanced tutorials, we still can have only one -- with subpages. --[[User:Dhaumann|Dhaumann]] 17:41, 4 January 2007 (CET)
 
::::: this is a breadth-versus-depth organization issue, isn't it? i see no problem with having 5 or 6 tutorials covering a given topic as long as they each cover a separate, distinct part of that topic. that distinction can come in many forms: introductory vs advanced, commonly used vs niche aspects, topics that each fill a good sized article. one thing i'd really suggest we avoid is having tutorials that try and cover every aspect of a technology resulting in huuuuge documents that are onerous to read and which make it more difficult to find exactly the bit you want. the xmlgui tutorials for kde2/3 were great examples of this latter problem imho. you'd get stuff that was too advanced for the new developer and the nuggets of gold that the advanced dev needs from time to time hidden quite effectively amongst the intro stuff. =/
 
::::: that said, i can certainly see the possibility of needing to eventually move all the tutorials for a given topic to a subpage of their own, much as this tutorial (the kde4 programming tutorial) is doing for "introductory tutorials". i see this becoming an issue once we have, say, >100 tutorials but until then i'm not sure we'll be able to best see how to organize the final content. i think building the library is the most important aspect at the moment. --22:03, 4 January 2007 (CET)
 
== Off topic tutorial stubs don't belong here! ==


Why do we have this tutorial on this page? It's KDE3 only. Surely there's a better place it could be put?
This page is '''NOT''' a dumping ground for all the small tips you couldn't find anywhere else for. This is a small series of tutorials for introducing a completely new programmer to the KDE API and build system etc. We don't need a tutorial telling the reader how to implement a QTreeView for example. That's what the Qt docs are for! I'll leave these up for a week incase someone wants to move these somewhere more appropriate after which point I will delete all these stubs. The CMake tutorial should perhaps be slimmed down and included into the CMake tutorial in the Development/Tutorials page. The XML parser tutorial isn't really needed, that's not the sort of thing someone looks up documentation for. That's what we have the Qt XML stuff for. --[[User:Milliams|milliams]] 15:14, 31 May 2007 (CEST)

Latest revision as of 13:14, 31 May 2007

Moving "Getting Help"

Getting Help/Contact belongs to the Contact / Contribute pages, not into this tutorial itself (it only bloats up the page) - what do you think? Dhaumann 17:05, 23 December 2006 (CET)

Fully agree, but I didn't see a good place to put this when I was writing it. So I just tacked it on here. Suggestions on a specific page it should go to? Mattr 18:36, 23 December 2006 (CET)
Maybe add it somewhere to Contribute or even put it into the Help: namespace? I'm yet undecided :) Dhaumann 16:54, 26 December 2006 (CET)
personally i think the "finding other developers" belongs in the Getting Started area, as it's something that anyone working on a kde application would want or even need to do. the finding documentation section could perhaps be broken out into it's own little tutorial? that tutorial could cover: developer[new].kde.org, accessing api documentation online as well as locally via konqueror or kdeveloper (qt assistant?), lxr.kde.org ...?
While this is being decided, I'll move the "Your lessons" section near the top. Since, to be honest, if someone clicked on the "KDE 4 Programming Tutorial" link on the Tutorials page then they're going to be expecting tutorials, not a page full of non-tutorial txt. --milliams 00:29, 4 January 2007 (CET)
Okay, coming back to this again. This information needs to be in a easier to find place. At the moment it's the best source of information on the KDE IRC channels I can find anywhere and it needs to be more prominent. On kde.org, this sort of info is under "Getting Started" but I'm not sure where it belongs on TechBase (if at all). Perhaps some sort of Contact page or maybe it should all simply be put on kde.org? --milliams 01:10, 11 March 2007 (CET)

Breaking this out into separate tutorials?

I have to say that this seems to be duplicating much of intent of the Tutorials section in general. The topics are pretty eclectic (nearly random?) and would each make nice top-level tutorials where they would be more visible and likely gain more editing love as well as readership. thoughts?

I feel that this page should just be introductory tutorials about the basics of KDE4 programming. The others (like printing and sound) should be moved to the main Tutorials page. -- milliams
I decided that instead of just saying 'should', I've gone ahead and written some tutorials which are aimed at developers complely new to KDE (but who know C++ (and maybe Qt)). I've also reformatted the 'First Program' tutorial to fit in with mine (to make a series of it). --milliams 22:55, 3 January 2007 (CET)
the tutorials look great. but i'm once again struck by the thought that these simply don't belong here but on the main tutorials page. tutorial #4 is about kconfigxt. we already have a tutorial on kconfigxt on the main tutorials page, and i'd suggest that is where this one belongs as well. if it's meant to be a more introductory piece than the existing one (e.g. introduces KConfig and friends, etc), then it can be placed before it (and perhaps even numbered appropriately?). if someone comes to the site asking "what does kde provide for configuration?" will they really find it all if that information is in the "beginner's tutorial" and some of that information is on the main tutorials page? and will people working on kconfig (to keep picking on that example ;) remember to update all the kconfig related tutorials spread around the tutorials area? i'm willing to help move things around on friday, but i don't want to do that without the blessings of those involved in authoring this set of rather nice tutorials... aseigo
OK, agreed. My KConfig tutorial should be on the main tutorial page along with the main KConfig intro. I see two possible ways to sort out what to do with the rest: (1) This page should be renamed to something like "Introduction to KDE Programming" The three (tutorial 1-3) tutorials I wrote should stay here since they are really aimed at completely new KDE developers but all the rest should be moved to appropriate places on the main Tutorial page. (2) All the tutorials should be moved to the main tutorial page and put in sensible places but that the three (tutorial 1-3) tutorials that I wrote should be put under a new heading and names with the 101, 110 etc. naming scheme. --milliams 14:06, 4 January 2007 (CET)
What I really think would work well is something like what the Qt documentation has at Qt 4.2: Qt Examples. Here they've written a series of tutorials (the one that build up an application, introducing one concept at a time) and then, after that, have got a largish number of 'examples' where they show you how to use a specific technology/widget/concept. The latter, I feel, is covered by the tutorials on the main tutorial page (i18n/solid/dbus etc.) but I do think we need a simple introductory tutorial which walks the new developer through KDE programming which is what I feel this page should aim for. --milliams 14:06, 4 January 2007 (CET)
i agree that we need a basic "getting started" tutorial; i also think your efforts here are doing a great job providing exactly that. i also agree that the tutorials on the main page should serve a similar purpose to Qt's examples (though hopefully we can structure it a bit better even). perhaps instead of covering kconfigxt in tutorial 4, you could cover "just" kconfig itself? that seems like a basic introductory concept. and then point from there to the article on kconfig xt (which adds all the xml stuff to the mix). kapplication, mainwindow, actions, config .. those are pretty universal concepts. most everything else varies from app to app based on needs/scope/audience of the app imho. so ... sounds like we're at an agreement point here? --Aseigo 22:02, 4 January 2007 (CET)
Just a quick sidenote: I think it's bad to have 10 tutorials of the same thing (a bit exaggerated =). Let's try to have only one. And if we need more advanced tutorials, we still can have only one -- with subpages. --Dhaumann 17:41, 4 January 2007 (CET)
this is a breadth-versus-depth organization issue, isn't it? i see no problem with having 5 or 6 tutorials covering a given topic as long as they each cover a separate, distinct part of that topic. that distinction can come in many forms: introductory vs advanced, commonly used vs niche aspects, topics that each fill a good sized article. one thing i'd really suggest we avoid is having tutorials that try and cover every aspect of a technology resulting in huuuuge documents that are onerous to read and which make it more difficult to find exactly the bit you want. the xmlgui tutorials for kde2/3 were great examples of this latter problem imho. you'd get stuff that was too advanced for the new developer and the nuggets of gold that the advanced dev needs from time to time hidden quite effectively amongst the intro stuff. =/
that said, i can certainly see the possibility of needing to eventually move all the tutorials for a given topic to a subpage of their own, much as this tutorial (the kde4 programming tutorial) is doing for "introductory tutorials". i see this becoming an issue once we have, say, >100 tutorials but until then i'm not sure we'll be able to best see how to organize the final content. i think building the library is the most important aspect at the moment. --22:03, 4 January 2007 (CET)

Off topic tutorial stubs don't belong here!

This page is NOT a dumping ground for all the small tips you couldn't find anywhere else for. This is a small series of tutorials for introducing a completely new programmer to the KDE API and build system etc. We don't need a tutorial telling the reader how to implement a QTreeView for example. That's what the Qt docs are for! I'll leave these up for a week incase someone wants to move these somewhere more appropriate after which point I will delete all these stubs. The CMake tutorial should perhaps be slimmed down and included into the CMake tutorial in the Development/Tutorials page. The XML parser tutorial isn't really needed, that's not the sort of thing someone looks up documentation for. That's what we have the Qt XML stuff for. --milliams 15:14, 31 May 2007 (CEST)