While I'm sure a dynamic site would be a great idea in the far future, are there any small, actionable goals we can make for this?
We all dream of a great docs scenario, but we never properly plan for it. What small wins can we get today, right now, to improve the experience? I have some free time to hack on it. On Thu, Sep 4, 2014 at 10:50 AM, Frederic Peters <[email protected]> wrote: > Allan Day wrote: > > > 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 > > 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 - 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. > > There's some documentation, and it's even up-to-date up to the point > that several persons got it running locally, but it has a long > hack/build cycle by default (as it will cover all modules from > multiple GNOME releases), and is using XSL transformations, and many > persons find this arcane. > > That structure made sense back in the day (2006) but given the way > other tools evolved (gtk-doc, yelp-tools), and better sysadmin > infrastructure (it was difficult to get new packages installed on the > RHEL version that was used until recently), it should be done > differently now. > > > > * 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. > > I gave my opinion in that previous email, "I'd go with a dynamic > website, as this would solve the issue of stale files, and offer > better ways to integrate important things, like search." > > (the stale files issue is the problem Jasper talked about, we get > Google indexing files way suboptimally) > > > > * 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). > > There are several layers here, most of the documentation still comes > from C files, via gtk-doc, then from docbook, gtk-doc again. This is > the bulk of what gets published, even for more "textual" content > (migrating from GTK+ 2.x to GTK+ 3 for example); then we have other > HTML generators, like Doxygen for the C++ bindings. The other > documents, the Mallard pages in the platform overview or developer > demos, the few wiki pages, are a really tiny part. > > > 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. > > > > Fred > _______________________________________________ > desktop-devel-list mailing list > [email protected] > https://mail.gnome.org/mailman/listinfo/desktop-devel-list > -- Jasper
_______________________________________________ desktop-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
