Re: Attacking the documentation monster

[Willow Liquorice]

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?

Thanks,
        Willow

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