Re: Documentation - language default

[Emmanuele Bassi <ebassi gmail com>]

On 4 April 2018 at 19:39, Sriram Ramkrishna <sri ramkrishna me> wrote:

Some of you may be aware that we have started a documentation effort in order to give application developers a proper set of documentation for them to write applications.

We need to optimize for one language rather than promoting all the languages.

This was the conclusion of the 2013 DX hackfest:

  https://treitter.livejournal.com/14871.html

and we all know how that turned out:

 - people (correctly or not) equated the "we chose to concentrate on _javascript_" as "everyone should use _javascript_ for GNOME"

 - the messaging of "we chose to concentrate on _javascript_" pissed off every other language community that had a sizeable presence in GNOME (Python, most of all)

 - the announcement was made without resourcing, in the *hope* somebody would turn up

 - we had to publicly backtrack on the messaging for the following 5 years

But, hey: we got a good _javascript_ experience, right?

Well, not really.

  In the past, we have promoted _javascript_ above all else.  We haven't seen as much movement in  _javascript_ allegedly because the toolchain has not been as robust as the other languages.

Mostly because "promoting _javascript_" from a documentation point of view isn't related to toolchain improvements.

The people that can write documentation are not the ones that are going to hack on

 - the documentation platform

 - the JS engine

 - the plethora of tooling necessary to work and debug applications

Even with the first item we've failed. We've had, what? 4 or 5 documentation hackfests in the past 5 years, and all of them have a line item about having better documentation platforms for our *C* API reference.

I really don't want to take a dig at anybody at the DX and documentation hackfests — they are all volunteers and they work *really* hard. The job is daunting in the best case scenario of somebody actually paying for this stuff; that we have documentation already is kind of a miracle.

Since this conversation could easily get derailed,

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 I would like to focus on is using _javascript_ as the default computer language for developing 3rd party apps on the GNOME platform.  We would like to validate what the current state of _javascript_ is for writing applications and whether we now have good support in flatpak, debugging toolchains (eg gjs and builder) and other factors we might have not considered but should be identified.

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?

More importantly: what are you planning to do if you find issues?

Let's say that _javascript_ fails to clear some arbitrary bar you defined — and I'd really like to see how you define these bars to be cleared first — what are the contingencies? Launch a D20 and choose another language?

 

Any input in this regard would be well appreciated to drive good documentation to write applications for the GNOME platform.

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.

Ciao,

 Emmanuele.

--

https://www.bassi.io
[@] ebassi [@gmail.com]