[Elementary-dev-community] Developer documentation (was: Google Summer of Code Ideas)
Hey guys, So I've checked out the current documentation in the website again and turns out it's quite useless. In addition to all the flaws I've already listed (quoted below for your convenience), it has no intro to Granite.Application or our widgets - in fact, it doesn't even mention Granite! All we have there is a Vala/GTK3 hello world. Is that *really*the intended content? I know Dan was not fond of the older dev guide draft ( http://tiny.cc/dev-guide-draft) but it, despite its many flaws, at least it had actual useful content! I'm afraid we're taking the don't do anything to not make any mistakes approach here, except we make mistakes anyway. Are we going to do something about this maybe? 2014-02-19 18:31 GMT+04:00 Sergey Shnatsel Davidoff ser...@elementaryos.org: In the dev guide we should at least link to http://valadoc.elementaryos.org/granite/index.htm for API reference, link to Vala tutorial https://live.gnome.org/Vala/Tutorial and migrationhttps://wiki.gnome.org/Projects/Vala/ValaForJavaProgrammers guides https://wiki.gnome.org/Projects/Vala/ValaForCSharpProgrammers, and to some GTK+ tutorial (GNOME developer screencasts?). We're also missing documentation on libswitchboard and Contractor; creation of Switchboard plugs via libpantheon is kinda sorta documented, but we've ditched that for libswitchboard and there are no docs on that in the website. Gotta fix that. Finally, we have Contractor; we used to have .contract file format documentation in the old website but it's now gone. The Granite wrapper API is *sort of* documented in the Granite valadoc, but the version in the website is pre-0.2.2 and doesn't include some useful 0.2.2+ symbols. The D-bus API is documented in Contractor specificationhttps://docs.google.com/document/d/1Ijsc57vYEHBZxVdM0fRgCuBX2NbdRDv1kuOj0OG75v4/edit?usp=sharingonly, which is obscure and nobody will ever find. I have example code for both the Vala wrapper and raw API in https://code.launchpad.net/~elementary-pantheon/contractor/contractor-clibut that's a very obscure location too. -- Sergey Shnatsel Davidoff -- Mailing list: https://launchpad.net/~elementary-dev-community Post to : elementary-dev-community@lists.launchpad.net Unsubscribe : https://launchpad.net/~elementary-dev-community More help : https://help.launchpad.net/ListHelp
Re: [Elementary-dev-community] Developer documentation (was: Google Summer of Code Ideas)
Completely disagree. I've had multiple people say that it's the best documentation they've ever read and I think it's the only existing end-to-end documentation that shows you how to build and package a simple app in all of FOSS. Yes it's incomplete, but it sets a strong foundation and actually gives you solid results quickly throughout the guide and does include several find out more links. The old docs were overly complicated, impossible to follow, showed you how to do things the wrong way, and just left a newbie developer with the impression that writing apps for our platform is an impossibly difficult task. They tried to do too much and lacked focus on what new developers need: a path to how apps on our platform are built and distributed. Yes, we need to continue the docs. But absolutely not in the old style. Cheers, Daniel Foré elementaryos.org On Sat, Feb 22, 2014 at 3:05 AM, Sergey Shnatsel Davidoff ser...@elementaryos.org wrote: Hey guys, So I've checked out the current documentation in the website again and turns out it's quite useless. In addition to all the flaws I've already listed (quoted below for your convenience), it has no intro to Granite.Application or our widgets - in fact, it doesn't even mention Granite! All we have there is a Vala/GTK3 hello world. Is that *really*the intended content? I know Dan was not fond of the older dev guide draft ( http://tiny.cc/dev-guide-draft) but it, despite its many flaws, at least it had actual useful content! I'm afraid we're taking the don't do anything to not make any mistakes approach here, except we make mistakes anyway. Are we going to do something about this maybe? 2014-02-19 18:31 GMT+04:00 Sergey Shnatsel Davidoff ser...@elementaryos.org: In the dev guide we should at least link to http://valadoc.elementaryos.org/granite/index.htm for API reference, link to Vala tutorial https://live.gnome.org/Vala/Tutorial and migrationhttps://wiki.gnome.org/Projects/Vala/ValaForJavaProgrammers guides https://wiki.gnome.org/Projects/Vala/ValaForCSharpProgrammers, and to some GTK+ tutorial (GNOME developer screencasts?). We're also missing documentation on libswitchboard and Contractor; creation of Switchboard plugs via libpantheon is kinda sorta documented, but we've ditched that for libswitchboard and there are no docs on that in the website. Gotta fix that. Finally, we have Contractor; we used to have .contract file format documentation in the old website but it's now gone. The Granite wrapper API is *sort of* documented in the Granite valadoc, but the version in the website is pre-0.2.2 and doesn't include some useful 0.2.2+ symbols. The D-bus API is documented in Contractor specificationhttps://docs.google.com/document/d/1Ijsc57vYEHBZxVdM0fRgCuBX2NbdRDv1kuOj0OG75v4/edit?usp=sharingonly, which is obscure and nobody will ever find. I have example code for both the Vala wrapper and raw API in https://code.launchpad.net/~elementary-pantheon/contractor/contractor-clibut that's a very obscure location too. -- Sergey Shnatsel Davidoff-- Mailing list: https://launchpad.net/~elementary-dev-community Post to : elementary-dev-community@lists.launchpad.net Unsubscribe : https://launchpad.net/~elementary-dev-community More help : https://help.launchpad.net/ListHelp
Re: [Elementary-dev-community] Developer documentation (was: Google Summer of Code Ideas)
Daniel, could you elaborate on why it was the wrong way? I discovered that doc with this thread and was tempted to follow some points, specially with Granite. Cheers, Marco - On Sat, Feb 22, 2014 at 5:59 PM, Daniel Foré dan...@elementaryos.org wrote: Completely disagree. I've had multiple people say that it's the best documentation they've ever read and I think it's the only existing end-to-end documentation that shows you how to build and package a simple app in all of FOSS. Yes it's incomplete, but it sets a strong foundation and actually gives you solid results quickly throughout the guide and does include several find out more links. The old docs were overly complicated, impossible to follow, showed you how to do things the wrong way, and just left a newbie developer with the impression that writing apps for our platform is an impossibly difficult task. They tried to do too much and lacked focus on what new developers need: a path to how apps on our platform are built and distributed. Yes, we need to continue the docs. But absolutely not in the old style. Cheers, Daniel Foré elementaryos.org On Sat, Feb 22, 2014 at 3:05 AM, Sergey Shnatsel Davidoff ser...@elementaryos.org wrote: Hey guys, So I've checked out the current documentation in the website again and turns out it's quite useless. In addition to all the flaws I've already listed (quoted below for your convenience), it has no intro to Granite.Application or our widgets - in fact, it doesn't even mention Granite! All we have there is a Vala/GTK3 hello world. Is that *really*the intended content? I know Dan was not fond of the older dev guide draft ( http://tiny.cc/dev-guide-draft) but it, despite its many flaws, at least it had actual useful content! I'm afraid we're taking the don't do anything to not make any mistakes approach here, except we make mistakes anyway. Are we going to do something about this maybe? 2014-02-19 18:31 GMT+04:00 Sergey Shnatsel Davidoff ser...@elementaryos.org: In the dev guide we should at least link to http://valadoc.elementaryos.org/granite/index.htm for API reference, link to Vala tutorial https://live.gnome.org/Vala/Tutorial and migrationhttps://wiki.gnome.org/Projects/Vala/ValaForJavaProgrammers guides https://wiki.gnome.org/Projects/Vala/ValaForCSharpProgrammers, and to some GTK+ tutorial (GNOME developer screencasts?). We're also missing documentation on libswitchboard and Contractor; creation of Switchboard plugs via libpantheon is kinda sorta documented, but we've ditched that for libswitchboard and there are no docs on that in the website. Gotta fix that. Finally, we have Contractor; we used to have .contract file format documentation in the old website but it's now gone. The Granite wrapper API is *sort of* documented in the Granite valadoc, but the version in the website is pre-0.2.2 and doesn't include some useful 0.2.2+ symbols. The D-bus API is documented in Contractor specificationhttps://docs.google.com/document/d/1Ijsc57vYEHBZxVdM0fRgCuBX2NbdRDv1kuOj0OG75v4/edit?usp=sharingonly, which is obscure and nobody will ever find. I have example code for both the Vala wrapper and raw API in https://code.launchpad.net/~elementary-pantheon/contractor/contractor-clibut that's a very obscure location too. -- Sergey Shnatsel Davidoff-- Mailing list: https://launchpad.net/~elementary-dev-community Post to : elementary-dev-community@lists.launchpad.net Unsubscribe : https://launchpad.net/~elementary-dev-community More help : https://help.launchpad.net/ListHelp
Re: [Elementary-dev-community] Developer documentation (was: Google Summer of Code Ideas)
Marco, It's been a while, but there are comments on the doc. I remember there being a lot of inappropriate things from a design perspective. But since that time we've also deprecated or changed a lot of stuff in granite, so I have no idea how relevant it even is anymore. Your best granite reference right now is probably finding an app that does the thing you want to do and looking at the code Cheers, Daniel Foré elementaryos.org On Sat, Feb 22, 2014 at 4:54 PM, marco benzi marco.be...@alumnos.usm.cl wrote: Daniel, could you elaborate on why it was the wrong way? I discovered that doc with this thread and was tempted to follow some points, specially with Granite. Cheers, Marco - On Sat, Feb 22, 2014 at 5:59 PM, Daniel Foré dan...@elementaryos.org wrote: Completely disagree. I've had multiple people say that it's the best documentation they've ever read and I think it's the only existing end-to-end documentation that shows you how to build and package a simple app in all of FOSS. Yes it's incomplete, but it sets a strong foundation and actually gives you solid results quickly throughout the guide and does include several find out more links. The old docs were overly complicated, impossible to follow, showed you how to do things the wrong way, and just left a newbie developer with the impression that writing apps for our platform is an impossibly difficult task. They tried to do too much and lacked focus on what new developers need: a path to how apps on our platform are built and distributed. Yes, we need to continue the docs. But absolutely not in the old style. Cheers, Daniel Foré elementaryos.org On Sat, Feb 22, 2014 at 3:05 AM, Sergey Shnatsel Davidoff ser...@elementaryos.org wrote: Hey guys, So I've checked out the current documentation in the website again and turns out it's quite useless. In addition to all the flaws I've already listed (quoted below for your convenience), it has no intro to Granite.Application or our widgets - in fact, it doesn't even mention Granite! All we have there is a Vala/GTK3 hello world. Is that *really*the intended content? I know Dan was not fond of the older dev guide draft ( http://tiny.cc/dev-guide-draft) but it, despite its many flaws, at least it had actual useful content! I'm afraid we're taking the don't do anything to not make any mistakes approach here, except we make mistakes anyway. Are we going to do something about this maybe? 2014-02-19 18:31 GMT+04:00 Sergey Shnatsel Davidoff ser...@elementaryos.org: In the dev guide we should at least link to http://valadoc.elementaryos.org/granite/index.htm for API reference, link to Vala tutorial https://live.gnome.org/Vala/Tutorial and migrationhttps://wiki.gnome.org/Projects/Vala/ValaForJavaProgrammers guides https://wiki.gnome.org/Projects/Vala/ValaForCSharpProgrammers, and to some GTK+ tutorial (GNOME developer screencasts?). We're also missing documentation on libswitchboard and Contractor; creation of Switchboard plugs via libpantheon is kinda sorta documented, but we've ditched that for libswitchboard and there are no docs on that in the website. Gotta fix that. Finally, we have Contractor; we used to have .contract file format documentation in the old website but it's now gone. The Granite wrapper API is *sort of* documented in the Granite valadoc, but the version in the website is pre-0.2.2 and doesn't include some useful 0.2.2+ symbols. The D-bus API is documented in Contractor specificationhttps://docs.google.com/document/d/1Ijsc57vYEHBZxVdM0fRgCuBX2NbdRDv1kuOj0OG75v4/edit?usp=sharingonly, which is obscure and nobody will ever find. I have example code for both the Vala wrapper and raw API in https://code.launchpad.net/~elementary-pantheon/contractor/contractor-clibut that's a very obscure location too. -- Sergey Shnatsel Davidoff-- Mailing list: https://launchpad.net/~elementary-dev-community Post to : elementary-dev-community@lists.launchpad.net Unsubscribe : https://launchpad.net/~elementary-dev-community More help : https://help.launchpad.net/ListHelp
