elementary-dev-community team mailing list archive

["marco benzi" <marco.benzi@xxxxxxxxxxxxxx>]

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é <daniel@xxxxxxxxxxxxxxxx>
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
> <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