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 desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list