Re: Feedback from downstreams presentation from DX hackfest 2015

[Philip Chimento <philip chimento gmail com>]

On Mon, Feb 2, 2015 at 6:37 AM, Philip Withnall <philip tecnocode co uk> wrote:

On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote:
> On Mon, Feb 02, 2015 at 08:05:00AM +0000, Philip Withnall wrote:
> > It was suggested that I send the presentation to DDL, since it might be
> > of general interest. I haven’t modified it from the hackfest version, so
> > please let me know if you have any questions.
>
> Can we assume that most still needs to be actioned? Also interested what
> discussions there were during the hackfest to improving this. E.g.
> Should we maybe reach out to our advisory board? Some things mentioned
> lack of documentation. So with DX hackfest and documentation at same
> time I also wonder if there were any possibilities to improve this.

Some of the items need actioning via bugs, which I will sort out. Some
of them have already been fixed (either as part of the client work by
Collabora, or by others in the time since). Some of them are unfixable,
and can only be used as general guidelines for trying to avoid such
problems in future (e.g. in new API designs).

Thanks for sharing! One point from the slides was familiar enough to jump out at me, and it's a bit of a strange one because it's not actionable via a bug report nor a matter of API design:

> "New functionality needs documenting: GtkBuilder templates were blogged about extensively, but are given a single sentence in the manual"

This actually happens quite a lot, in my experience. For someone just starting out, blogs are not very discoverable, and they won't know the blogger by name as "maintainer of X". I wonder if we could take this existing enthusiasm for documenting something in a blog post and channel it into the API docs. For example I really like your own occasional series of posts about GObject stuff (e.g. [1]) but it would probably help more people if something like these code examples existed in the API docs.

I do get that blog posts are more fun to write because they are informal, and they also build your reputation online whereas API docs are anonymous.

[1] https://tecnocode.co.uk/2014/12/19/use-g_set_object-to-simplify-and-safetyify-gobject-property-setters/

Best,

--

Philip