On Mon, Feb 2, 2015 at 6:37 AM, Philip Withnall <[email protected]> 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
_______________________________________________ desktop-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
