[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Attacking the documentation monster

From: Willow Liquorice
Subject: Re: Attacking the documentation monster
Date: Fri, 20 May 2022 01:21:17 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.8.1

I've got some free time on my hands now, and I gave some thought to improving the readability of the HTML documentation on the website (which is what the average prospective GNUnet dev is going to look at). Read the Docs and friends set the standard in this regard. Having the contents in a sidebar for easy access (regardless of your location) would be far more convenient than what's currently available.

I understand that TeXinfo's HTML generation is a bit simplistic in the name of compatibility, which, while not a bad thing, results in a subpar reading experience for the average dev who will, in all likelihood, be reading the docs on a very capable modern browser.

While thinking about how to improve things with TeXinfo, it occurred to me that, instead of trying to emulate the experience of using Read the Docs, one could just use Read the Docs! It's Free Software, after all. I haven't looked into it too deeply, but if the .texi sources are converted to the reStructuredText that it accepts, a migration (or use of a similar platform) might be worth considering. What do the people here think?

If I'm going to dedicate time to restructuring GNUnet's docs, I need to know where it all is. I've found four strands of docs in the repository (Handbook, Tutorial, Doxygen, and man pages), could someone give me a run-down of the state they're in, how they relate to one another, and what they're supposed to be for? Is that everything?


On 01/03/2022 22:52, Christian Grothoff wrote:
Spam killed this. We already constantly have to delete 'bug reports'
from the Web that were submitted as link spam. A wiki will drain
resources to keep the spammers out, and at the same time experience says
the contributions will be low quality (it has been tried).

If someone really is capable and invests time into contributing to
documentation, they can pick up Git and send patches.

On 3/1/22 11:12 PM, madmurphy wrote:
I don't know if this will be a popular proposal, but I really believe
that setting up a self-hosted Wiki could be a very good choice. No
complicate git clone, no complaints, just read/edit what you need, and
distributed responsibilities about its design and direction.

My two cents

reply via email to

[Prev in Thread] Current Thread [Next in Thread]