On 27/02/2022 14:47, madmurphy wrote: > Hi Bob, > > These might be worth reading: > > * GNUnet handbook <https://docs.gnunet.org/handbook/gnunet.html>,
This is more confusing than helpful. I'll paste an abridged rant from IRC: 12:06 < rah> the handbook is a mess 12:08 < rah> I mean really, the handbook should be thrown out and rewritten from scratch, it's more confusing than helpful 12:10 < rah> why are "Configuring your peer", "Configuring the MySQL database", "Configuring the hostlist to bootstrap" and pretty much everything else, under a section titled "The graphical configuration interface"? 12:10 < rah> it's ridiculous 12:12 < rah> why does the "Checking the Installation" section only list graphical programs? 12:12 < rah> I'm running a node on a headless machine 12:12 < rah> and right now I'm on a machine with no X server so I can't run any graphical programs remotely 12:14 < rah> there's a section "4.9 Config Leftovers" that starts "This section describes how to start a GNUnet peer." 12:14 < rah> why on earth does that come after detailed instructions on configuring mysql? 12:15 < rah> there's a section "8.20 Bluetooth plugin" which starts "This page describes the new Bluetooth transport plugin for GNUnet." 12:15 < rah> why is that section part of the "GNUnet Developer Handbook"?! 12:16 < rah> the whole document is a mess that doesn't help a new user at all, in fact it makes things more confusing 12:16 < rah> the whole system is opaque and the handbook gets in the way of understanding it > * How to use GNUnet - in a nutshell <https://www.gnunet.org/en/use.html> In my view, this document is problematic because it doesn't really explain anything. When I was trying to get my node up and running, none of the commands worked. There's a common theme in gnunet's documentation which is to provide instructions. I don't need instructions, I need information. Also, the instructions are pitched at a level of expertise which is unrealistic; as I understand it gnunet is not usable at present so the people who will be looking at the documentation will not be wide-eyed users who need a helping hand, they'll be hackers who need clear, useful information. It's like the documentation is written for the benefit of users in some future when gnunet is functional and usable, not for the benefit of people who will be coming to gnunet right now. Regards, Bob
