Should the code to manage GIMP docs evolve?
Hi documenters!
I have been looking at the doc code on GIMP side today and I was amazed how this was over-engineered unless I am missing something critical. Hence this report which is more for a discussion on whether or not I am missing this something, if you would like the docs infrastructure to evolve or not, if so how we should evolve it, or if you are just fine with everything and wonder why I even bother.
Anyway so from GIMP code, I can see we are basically just generating a URL from the lang and help ID like this: https://docs.gimp.org/2.99/ + lang + help_id. Sometimes we would also parse a XML file (https://docs.gimp.org/2.99/en_US/gimp-help.xml) to map the help ID to another URI, for instance file-png-save docs is actually at https://docs.gimp.org/2.99/en_US/gimp-images-out.html#file-png-save
For all of this, on GIMP side, it seems we actually have thousands of line of code, with some core code, the help
plug-in, but also either the web-browser plug-in (when we redirect to the system browser) or the help-browser plug-in (when we use our custom WebkitGTK-based browser plug-in). All of this to… combine pieces of URI and display them in a browser. That's the first thing I don't get because it feels to me it could be done in a few lines (well except for our custom browser plug-in but there are discussions about dropping it anyway because recent WebkitGTK doesn't build on Windows anyway).
On the documentation side, this seems also quite a complicated build system we have here (more than 1 hour to build for all languages, though I know HTML generation is often a bit long). I tried to read the Manualstructure.txt from the repo but all the links to our wiki are dead (even just searching the page names doesn't return anything relevant).
So my questions now:
- Is there anyone here who understands the technical behind-the-scene of this documentation (either on GIMP side or docs side) and wants to explain why things are done this complicated way?
- When we add help IDs on GIMP side (we do when we create new plug-ins for instance), how do you know it currently? For instance, we had relatively recent WebP support but I can see there is no page for
file-webp-save
so anyone trying to read the WebP format dialog docs reach a "help missing" page. It feels like we should have some better communication (but maybe you have a way to get these IDs, you just haven't had time to make the new docs yet). - Are you (current contributors) all fine with the way things are and don't really want to change?
- If you were to change, which direction or technology you'd like to go?
For instance, maybe we could go for a simpler docs structure where one help ID is one file.
And what about simpler markup languages (like markdown or restructuredText) which are being used nowadays? These are definitely simpler in features than docbook but they can be extended and how I see our docs, they don't seem to need crazy features. The contents of our official website for instance is fully generated from markdown and it makes writing news much simpler IMO.
Of course, we should figure out a workflow to better communicate needed docs change if needed.
And so on. Basically I feel that our current docs situation is not ideal and maybe too complicated, so tell me if I'm wrong or not. If not, we should work on improve/simplify it.
Adding @mitch (maybe you know why things are the way they are), @patdavid (if we want to revamp a bit, you might be the ideal person to talk to!), also @Wormnest and @nielsdg (if you guys are interested to help in this topic too!).