Re: Revamping the developer documentation

[meg ford <meg387 gmail com>]

Hi Allan,

On Tue, Feb 26, 2013 at 6:39 AM, Allan Day <allanpday gmail com> wrote:

Marta Maria Casetti <mmcasetti gmail com> wrote:
> First of all: I really like the mockups.

Thanks Marta!

> I also think that we should try to include something for first-time
> programmers, like a tutorial, somewhere.

It would be really cool to have a good place for this material. My
sense (correct me if I'm wrong here) is that mixing docs for novices
with docs for experienced programmers might end in confusion on both
sides - the novices will find the advanced stuff too hard, and the
experienced developers will end up thinking that the developer site is
too basic for their needs. I'd also really like our main developer
site to focus on experienced developers - if we want third party
developers to use our platform, they need a resource that is designed
for their needs and which will help them get the information they need
quickly.

So the question is - where should the first-time programmer material
go? Do we want a separate section inside developer.gnome.org? Do we
want a sub-site? The latter seems like it might be a better option to
me - different audience, different design...

I think having useful information front and center makes sense, but we are trying to present an unfamiliar platform, so I think it's better to have some simple examples included on the main site. The majority of development is less complicated than coding for GNOME (I recently showed a friend of mine who writes options trading software using VBA and C++  some libxml functions, and he compared it to monks in the middle ages writing with pens, for example). Most developers want some examples when they are writing code in an unfamiliar language (and remember gjs is pretty different from standard _javascript_ on the web). If you look, for example, at the Android "Layouts" section [1], the examples given are beginner-level, but the accompanying text is directed at developers. I could list tons of examples here (Flask, Heroku, W3C Schools, Google Drive API, The Java Tutorials, etc) of developer docs that include simple starter code. If anything, it makes sense to me to include beginner-level information but tweak the presentation.

Meg

[1] http://developer.android.com/guide/topics/ui/declaring-layout.html

Allan
--
IRC:  aday on irc.gnome.org
Blog: http://afaikblog.wordpress.com/

_______________________________________________
gnome-doc-list mailing list
gnome-doc-list gnome org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list