Re: Documentation - language default

[Allan Day <aday gnome org>]

Emmanuele Bassi <ebassi gmail com> wrote:>:
...
> This was the conclusion of the 2013 DX hackfest:
>
>   https://treitter.livejournal.com/14871.html
...
>  - the announcement was made without resourcing, in the *hope* somebody
> would turn up

I don't think that's entirely true - my recollection is that there
were some people working in this area at the time. Also, it's worth
remembering that a lot of really awesome things that came out of that
hackfest, like GTK Inspector, popovers and baseline alignment. That
was also the event where we had a lot of critical discussions about
Flatpak and portals.

...
> That's probably the understatement of the year — *but* I think we'd be
> better served by actually going a bit deeper than just "let's evaluate a
> single language for our platform".
...
> What does "validate" mean? You want to write an application? What kind of an
> application?
>
> What does "good support in Flatpak" mean?
>
> What does "debugging toolchain" mean?
...

These are all important questions and you're right that there needs to
be a vision for what the developer experience ought to look like. My
best memory of GNOME doing this is actually the 2013 DX hackfest,
where we started out with a general discussion about who the target
audience was and what we wanted the overall experience to look like,
before breaking it down into individual pieces.

My view is that the challenge isn't so much coming up with a vision so
much as pushing it forward. For that to happen I think we need someone
to take a DX lead role in the project.

...
> While good documentation is a necessary stepping stone towards a decent SDK
> and application development experience, it's nowhere near sufficient.
>
> You can have the best documentation in the world — but if you don't have
> people working on the tooling and the actual integration between the
> language and the platform, then you don't have anything that other people
> can use.

You're right that documentation alone doesn't make a great developer
experience, and we ought to be aware of and be working on gaps in the
experience.

However, we have some great technologies and tools available today
that we ought to be highlighting, and there are some relatively
achievable improvements that could be made to our documentation which
would have a massive impact. For example, it would be an incredible
improvement if we had:

 - a nicely designed documentation portal, which pointed to the best
resources we have available today
 - a page that provides a high-level overview of the development
process, along with the main tools
 - API docs for the interpreted languages
 - examples that we can point people to

Some of these are within reach, although as Bastian pointed out,
having the necessary infrastructure has been a stumbling block in the
past.

Allan