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 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 wereblogged 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.
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 upstream. 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? Philip [1]: http://blogs.gnome.org/mclasen/2014/07/28/a-talk-in-9-images/
Attachment:
signature.asc
Description: This is a digitally signed message part