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

[Nils Gillmann]

Hi,

Schanzenbach, Martin transcribed 6.5K bytes:
> Hi,
> 
> my 2 cents on the Installation Handbook:

thanks :)

> I actually thing that installing from source is not something the
>  average joe should have to do.

Me neither, but there are cases where you have to.

> Ideally there is an installer package (MSI,dmg/pkg,.deb/.rpm).

And some of the few cases include the OS which do not run with package managers.
It also includes...[x]

> Alternatively (and temporarily until we are in alpha/beta), we could
>  provide a docker image (maybe we get a project account there and

What does this mean? Get an account where? Do you mean
https://hub.docker.com/ ?

>  integrate the build into our future CI) then it is as simple as a
>  "docker run gnunet:latest".

I personally don't think docker is a good solution, it's good to check
it out but you need someone to maintain it.

> I think people that actually (have to) build from source and thus
>  must install dependencies as well are ideally only people who
>  develop or do packaging.

[x]... doing packaging on Operating Systems which do not / not yet
have a package for GNUnet and other software we depend on. I was able
to figure it out quickly in 2015, how to build GNUnet because some
instructions existed, and others were buried in the build-system.

> With that in mind, the Installation Handbook can assume the reader is quite 
> savvy.

I disagree to what I assume you mean as requiring some amount of
technical knowledge, but I think it works best if I present a next
version and get feedback.

My evaluation of the handbook so far always included asking what you'd
consider tech savy people and also all sort of people with a basic
understanding of computers but none whatsoever at how Operating
Systems work etc.  Even they (the tech savy ones) didn't understand
most sections (of the old writings).

I have 2 choices in writing:
Assuming the reader knows nothing.
Assuming the reader knows as much as I do.
It's harder but I prefer working in a way that what I write will be
understood by most people. Technical writing can be used, but I'm
still making up the ideal middle-path based on how other people
understand the documents.
Even as a tech savy person I like getting easy to understand
instructions.

Thing is, it should be accessible. We can't serve every case
and include everything (other, accompanying, books could do that).
What I want is that it can be understood by a broad range of
people. We don't get special points for expressing knowledge in
a way that you need to read into various topics to get it.
For subjects like 'ed25519' and so on it's okay. Too much text
can be difficult to comprehend, so descriptive pictures will be
included in the future.

Ideally it works like this: identify package manager. Look at
the command you need to run to install it. Done.
Containers belong elsewhere, like specifically a 'Installing
GNUnet in Docker' section or whatever that can be added later.
It's still good to have as some people will want this, but we
should only promote it if it's kept up to date.

To point out more 'easy to install' one liners I could list
TODO jobs (not in the documentation, at least not directly)
for people interested in system integration. Like,
I have started looking into BSDs and reasons why GNUnet was
dropped from FreeBSD ports (gnurl was one point), packaging
for smaller OS frameworks, getting GNUnet into Gentoo proper
is also just a tiny step,...

Thanks,
N.

> BR
> Martin
> 
> > On 3. Jun 2018, at 20:54, Nils Gillmann <address@hidden> wrote:
> > 
> > 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
> > 
> > _______________________________________________
> > GNUnet-developers mailing list
> > address@hidden
> > https://lists.gnu.org/mailman/listinfo/gnunet-developers
>