Re: Developer Docs Roadmap [was Re: Glade release to include GtkHeaderBar?]

[Allan Day <allanpday gmail com>]

Frederic Peters <fpeters gnome org> wrote:
...
> I would tend to put goals before technical details, but library-web as
> it is nowadays is certainly not the best option; I addressed a few of
> the issues in my mail to gnome-doc-devel-list   ...

> >  * Hackability ...

> >  * User experience ...

> >  * Documentation writing workflow ...

Thanks for the information here, Fred, and sorry for not replying to
your doc-devel-list email (I do remember reading it back before the
hackfest). It's definitely enough to get started on a design.

One of the reasons why I wanted to have this conversation is to find
out if there are any third party solutions that we could use, rather
than having to write and maintain our own site from scratch? Is Read
the Docs [1] an option?

> But to be honest, while the workflow can definitely be improved, I
> don't think it's the main obstacle. I look at user documentation, it
> gets written, it gets updated, and it's Mallard in git repositories.
>
> No, I think the obstacle is that we don't have enough people willing
> to work on developer documentation over something else, even though
> many will recognize the importance it has. It's not new.

The difference between user and developer documentation is that, to
write developer documentation, you need to understand the
technologies. This means that we have to rely on existing developers
to write the developer docs, and these people are, by definition,
already busy with other things. That's why we need to ensure that the
barrier to entry is low - if we want to tempt developers into writing
documentation, it needs to be really easy. The formula for the HowDoIs
is a good start here, and it would be good to build on that.

Allan

[1] https://github.com/rtfd/readthedocs.org