Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage

[Nils Gillmann]

Nils Gillmann transcribed 1.7K bytes:
> en3r0 transcribed 3.8K bytes:
> > Hi Nils,
> > 
> > I think that a good idea. I think it might be good to also include use case
> > examples. Although that may be better suited for another chapter outside of
> > installation.

Here's what I found (was remembered of) today:

All past work and authors did good work, but the point of view was too far off
to produce anything useful without trying to decipher it for people *new* to
UNIX and using computers in general. Developers who've forgotten what's it
like to be new to the whole thing. That's okay and happens to me too.

So to be honest, the handbook sucks as it is. The fact that some people were 
able
to make more sense of GNUnet with my edits than before is huge.. and 
mindblowing.

The structure is really weird. Okay, we are still looking at the 3rd revision
after the initial Drupal export and its edits finished. But like 50% of what I
considered to be Installation handbook material (it was in the 'installation'
Drupal book) is really just User handbook material.

You should read the User handbook when you're done installing. Want more 
in-depth
configuration? User handbook. Set up Nginx behing the VPN? User handbook.
Run an ircd and let other people connect to its gnunet vpn address? User 
handbook.
Basically I want section the User handbook which explain every necessary command
in GNUnet, and then give you examples to get started. Not just to get started 
but
to be interested and to *want* to read more, to be as excited as we are, reasons
why an almost 2 decades old codebase can be interesting. It's not that I think
old code is bad code, but there are people like this out there. University I'm
in sometimes preaches the whole 'rewrite codebases, old languages are bad' etc.

We have historic grown documentation snippets. It's okay that it's messy.

So what I'd consider an improvement is this, once I'm getting there:
I want you to read the whole 3+ books, which is a lot of pages, don't fall
asleep while reading it (you will need more than 1 evening to read the books)
and to understand most things, including how to reach out for help.
This would squash almost all problems people ever had with GNUnet.

...Then we only have website, general public relations outside of academia
and content left. Additionally there's interface specific improvements etc
but one step at a time.


While I'm at it: I've got some feedback last year and I'll look into
cross-compiling for Windows native, not for cygwin. There are problems,
but cygwin is a problem for people.


> > I know I was happy to get it installed but fell short in actually using it.
> >
> > On Sun, Jun 3, 2018 at 10:12 AM Nils Gillmann <address@hidden> wrote:
> > 
> > > Hi all,
> > >
> > > I took the recent reports and non-reports[0] I've read over the last year
> > > and decided the only good solution is a Bakunin one this time. So in
> > > Bakunin's tradition I'm erasing what we have and I'm rewriting the
> > > Installation Handbook.
> > > I might reuse some old parts, but basically I'm aiming for a 100% rewrite
> > > with this book.
> > >
> > > If anyone got improvement suggestions, post them here. For the next couple
> > > of days/weeks/month I'll be working on this. I'll check this thread before
> > > I'm wrapping it up. The recently added macOS instructions provide a good
> > > bbase for simply extending them in the new sections. The rest is almost
> > > always too much self-grown repetive imports from the original Drupal
> > > books.
> > >
> > > 0: non-reports: "circle of yelling in a social network echo chamber"
> 
> 
> Hi,
> 
> this is content present in another book ("Using GNUnet"), present in the
> source tree for quiet a while now. Everything is not ideal, so you are
> right on spot.. usage examples is what I'm looking for to include in the
> other book.
> I'm also considering to separate the books at some point into separate
> output files, since the index will (over time) grow very long.
> 
> Thanks
> 
> _______________________________________________
> GNUnet-developers mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/gnunet-developers