Re: Determining whether gnunet is connected

[Schanzenbach, Martin]

> On 1. Mar 2022, at 11:14, Bob Ham <rah@settrans.net> wrote:
> 
> 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

To be honest, I could have written this rant myself. The handbook would even get
in the way of actual coding because for some reason it goes into extreme detail
at some points and the churn of the codebase make this a tedious job.

I think we should definitely at least separate chapters 4-8 into individual 
pages.
The sheer length of the PDF/website is insane.

> 
> 
>>  * 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.

This was an attempt to provide an easier "getting things started" before you
are confronted with the handbook.

> 
> 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.
> 

Yes, good documentation is needed. I am myself guilty of neglecting it.
The biggest problem is that I do not even consider myself an expert of most
subsystems. And most subsystems are abandoned / effectively unmaintained.
I have raised the issue of complexity (which is why the documentation is also 
complex)
here: https://lists.gnu.org/archive/html/gnunet-developers/2019-02/msg00002.html

Maybe as rah suggests a fresh start is necessary, cannibalising parts of the 
handbook.
Such a "Documentation 2.0" project would be helpful and important.
At this point, unfortunately, I do not see myself doing that though because
there are more pressing issues than providing docs: Getting DHT, GNS and the
Transport in a functioning and more or less stable state and writing the 
specifications
for the DHT (which is currently funded so... yeah it takes priority).

Anybody willing to help with a documentation task is welcome.
Throwing suggestions into the ML may be futile, as there are currently
not enough workers to schedule this job to (and nobody likes writing 
documentation
in the first place).
In fact, once of the reasons we decided to drop the IRC as an official 
communications
channel was that we lack the manpower (and active community) atm to provide
responses there. The mailing list just reflects the communication pattern 
better.

So, anyone "feeling it" can just fire up an editor and start creating a texinfo 
with
a better documentation. We had hackathons to improve the docs before.
But the changes were not technical enough in nature and mostly editorial.
The last oddity cleaned up was a random "GNUnet is an anarchist network"
(wtf does that even mean).
If there are questions or feedback is required, post it here.

FWIW my latest attempt on making GNUnet more accessible started with this page:
https://www.gnunet.org/en/architecture.html
Now, the links on that page should point to better documentation. Or maybe 
other pages
that have more succinct explanations.
It is also why we started this: https://www.gnunet.org/en/applications.html

The website in general is a good starting point and it should lead into a 
(better) documentation.
Even if that means that a lot of subsystems will not be documented anymore 
because
the knowledge of them has been lost (looking at you regex, secretsharing, 
auction et al).

Maybe even the libp2p docs can be helpful for orientation (they have a lot more 
manpower than we
do I think).
But even there, the quality of docs is... questionable: 
https://docs.libp2p.io/concepts/secure-comms/ 
https://docs.libp2p.io/concepts/content-routing/


BR
Martin

> Regards,
> 
> Bob
>

signature.asc
Description: Message signed with OpenPGP