Frederic Peters <fpet...@gnome.org> wrote: ... > Since the hackfest in Norwich in January it's possible to get specific > modules online (almost) directly after the git commits. It is > configured that way for gnome-user-docs and gnome-getting-started-docs > (for help. gnome.org) and for gnome-devel-docs (developer.gnome.org).
Ah! That's good to know. > A few months ago I posted some plans and questions to the > gnome-doc-devel-l...@gnome.org mailing list, but probably I should > have asked people to subscribe there first :) So here they are: Yeah I'm subscribed, but I don't follow that list very closely. > Support for multiple programming languages & multiple versions: > > On a structure level, there are at least two important questions: what > kind of navigation do we want between programming languages (and > perhaps on a more fundamental level, how do we expose them?), and > between different versions of the libraries. At the time it was > important to have various versions available online, for exemple GTK+ > 2.6(?) was available because Nokia(?) used that version in their > developments, but today we may want to expose a more unified "this is > the current GNOME API" approach. (and that "bundle" approach would > also benefit devhelp) > > Covered libraries: > > This brings the question of the libraries we want on the developer > website, it started as just our core libraries, but requests after > requests, it got its share of other libraries. (but if we decide to > put them away, it's certainly also important to have a place for > them). The design team can certainly work on a new look for the existing site, along with how versioning could work, and we can turn this into a roadmap. As a part of that, we can take a look at how the material we have should be organised. However, before we go down that route, it seems like we should at least discuss whether library-web is the best option going forward. It seems like there are a number of issues with the existing infrastructure, which make me question whether we should be investing in it or going for something new/different: * Hackability - from what I've seen, it is very difficult for people to hack on developer.gnome.org. The barrier to entry is high, documentation is lacking, and it all seems rather obscure. * User experience - we need to decide whether developer.gnome.org should look and feel like a static website, or should be more like a web app. I was looking at Read the Docs [1] a while ago, and that kind of experience seemed like a good fit for API docs especially - search is prominent, you can quickly switch between documentation, etc. * Documentation writing workflow. Monolithic modules written in Mallard, like gnome-devel-docs, aren't approachable for developer documentation writers. The HowDoI series has been reasonably successful, partly because it is easy to write documentation on the wiki, but finding and navigating that material isn't great [2]. A middle ground might be appropriate (Markdown HowDoIs, perhaps). Then there's the whole question of the tool chain required to generate the API docs, which I'm not qualified to discuss... Allan [1] https://github.com/rtfd/readthedocs.org [2] https://developer.gnome.org/guides#tutorials _______________________________________________ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list