Re: Revamping the developer documentation

[Marta Maria Casetti <mmcasetti gmail com>]

Hi,

As I said on the #docs channel (but I should have had replied here
too, sorry!), I think it would not be bad to have both a page for more
experienced developers (but still with an example) and a page for
beginners (example-centred, with a "if you want to know more" link to
the "experienced developer" page). What would you think of that? Too
much work, for instance?

Best,
   Marta

On Tue, Feb 26, 2013 at 3:54 PM, meg ford <meg387 gmail com> wrote:
> 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