Future of Documentation
I'm opening this because we haven't done one in awhile, and I think it's worth a few points of view. It was also prompted by #87, which reminded me how scattered our documentation gets at times.
Some notes (feel free to GC my memory
-
The GJS TypeScript sub-community is thriving, and has excellent documentation (https://gjsify.org/pages/api-references)
I think this is a good time to revisit centralizing our efforts, although @JumpLink and @ewlsh are certainly more familiar with e.g. technical requirements for deployment. It's certainly obvious that developers are reaching for TypeScript and the IDE features that come with it, like type definitions, completions and inline documentation.
-
There was a time when @ptomato noted that it's a lot easier to keep GJS's self-documentation up to date if it shows up in git-grep along with code and tests
We already pull the
doc/
directory into https://gjs-docs.gnome.org/gjs/, but there may be more docs that should be in-repo and scraped into other sites when better presentation is desirable. -
Documentation doesn't scale in a one-to-many model
The reality of even GNOME Shell by itself, is that it covers so many different topics that the few people familiar with all of them don't have time to document on-the-fly. We do have a lot of community members that are familiar with at least one, and lowering the contribution barrier could make a big difference.
-
Everything is easier when we have specific topics and examples
@jrahmatzadeh does an amazing job with extension reviews and has developed excellent habits like linking directly to specific topics. Reduced friction for experienced developers inside the community is just as important, such as Julian Sparber jumping head-first into GNOME Shell for the new notification system.
Also cc-ing @fmuellner @sri @rmnvgr @sonny
I know this is a broad topic so feel free to take your time, invite friends, get a bit off-topic, or just throw some weird ideas out there