elementary-dev-community team mailing list archive

["Daniel Foré" <daniel@xxxxxxxxxxxxxxxx>]

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
<sergey@xxxxxxxxxxxxxxxx> 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 <
> sergey@xxxxxxxxxxxxxxxx>:
>> 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 migration<https://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 specification<https://docs.google.com/document/d/1Ijsc57vYEHBZxVdM0fRgCuBX2NbdRDv1kuOj0OG75v4/edit?usp=sharing>only, 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