Changing the Programming Guidelines to mdbook

Our old GNOME Programming Guidelines (rendered) are getting rather dated. I’d like to revive them with more contemporary content, and possibly a format change.

The document is done in Mallard markup. I’d be more comfortable with mdbook, which uses a much simpler Markdown syntax, and generates pretty web pages with some modern amenities. (I don’t want to bikeshed too much on the markup language - but while Mallard works very well for non-linear, pluggable online help, I don’t think it works well for linear, reference books like the Programming Guidelines.)

What are the deployment implications of this? I have no idea of how stuff in the gnome-devel-docs project gets rendered and uploaded to the docs site. Does anyone know?

4 Likes

Hi @federico,

I think this is a nice effort.

Couple of suggestions:

  1. Can we add the link to GNOME programming guidelines page, to all GNOME project wiki page under Development / Contribute section. I am not sure how many projects have them, but it would be good to have it, as most new GNOME contributers start their work based on the information provided in the wiki of the project of their interest.

  2. Would be nice, if we could have a PS / PDF rendered version too.

Thanks!

2 Likes

Adding rust into the doc toolchain will add some complications, I assume.