Re: Feedback from downstreams presentation from DX hackfest 2015

On Mon, 2015-02-02 at 19:56 -0800, Philip Chimento wrote:
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
        > > 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
        > 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
        and can only be used as general guidelines for trying to avoid
        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

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.

Totally agreed, and I’m very guilty of this. :-(

The only solution I can think of is for people to comment on such blog
posts and gently remind the author to ensure everything’s documented

Matthias did this quite well with one of his GUADEC GTK+ presentations
(IIRC [1]) where the presentation was basically just various bits of
upstream documentation which he had updated specially. Maybe we could
see more of that in future?



Attachment: signature.asc
Description: This is a digitally signed message part

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]