Hi all, As some of you know, I spent some time looking at the developer docs during the recent Developer Experience Hackfest. I was also able to have a short discussion about it yesterday at the Documentation Hackfest in Brno.
Here's a brief summary of the ideas that have come out of these discussions so far: * It would be great if all the developer documentation could consistently reflect a recommended process for developing a GNOME application (we sketched this out during the Dev X hackfest: design your application, create a UI with Glade, code using the recommended editor, test, add documentation, create a package or approach distros). * It would also be great if we could work towards having a complete set of application development documentation for JavaScript. this would align the developer documentation with efforts that are underway for tooling and generated API documentation. * In some of the discussions about the target audience for developer docs, it was proposed that the docs should be written for people with some programming experience, but who might not have been exposed to GNOME in the past. It was also suggested that, while we might want to have tutorials aimed at developers with different backgrounds (eg. Windows/OS X/web development), the core of the docs need to be background agnostic. This would imply that we wouldn't have tutorials that try to teach programming for the first time on developer.gnome.org (which isn't to say that we couldn't have this type of material elsewhere). * Another proposal was that developer.gnome.org should be targeted at application developers and not core GNOME development (again, this isn't to say that we shouldn't have docs for core GNOME development somewhere). * Having a more encompassing organisational structure would help us to identify what documentation is missing and should also help application developers find the help they need. One idea that came out of the Documentation Hackfest was that the developer docs could be structured around task areas, such as application integration, multimedia or creating UI. Each section could then include specific development tasks: "Writing a Desktop File", "Playing Audio", "Dialog Windows". * We need a new HIG, and it needs to be hosted on developer.gnome.org - I'm currently working on this. * It would be better to have a separate website for the user and sysadin documentation, so that developer.gnome.org is purely about developer docs. A number of these ideas are reflected in a small set of mockups I've done for developer.gnome.org [1, 2, 3]. There has been a bit of work done to implement this redesign, and that is something I would like to pursue. All of this is extremely tentative and it would be great to hear everyone's thoughts. It would be especially good to hear what the existing developer docs writers think. Allan -- IRC: aday on irc.gnome.org Blog: http://afaikblog.wordpress.com/ [1] https://raw.github.com/gnome-design-team/gnome-web/master/developer.gnome.org/wireframes/png/home.png [2] https://raw.github.com/gnome-design-team/gnome-web/master/developer.gnome.org/wireframes/png/tutorials.png [3] https://raw.github.com/gnome-design-team/gnome-web/master/developer.gnome.org/wireframes/png/api-reference.png _______________________________________________ gnome-doc-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gnome-doc-list
