gnunet-developers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [GNUnet-developers] documentation: Rewriting the Installation Handbo


From: Schanzenbach, Martin
Subject: Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
Date: Sun, 3 Jun 2018 23:58:04 +0200


> On 3. Jun 2018, at 22:33, Nils Gillmann <address@hidden> wrote:
> 
> 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.

Don't underestimate the usefulness of docker especially wrt to platforms.
A single docker images comes with GNUnet installed. It will run on macOS, linux 
and windows.
For anyone to get started quickly (i.e. using GNUnet), this is the way to go.
And yes, I mean hub.docker.com _if_ we also want users to have the slightly 
more comfortable way to refer to the gnunet image.
However, using a dev namespace, e.g. schanzen/gnunet:latest, is fine as well.
Alternatively, we could have our own docker registry, which might be a good 
idea if Taler also could make use of it in some way.

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

Well that first requires packages. I do not thing we are there yet so this part 
would be blank.

> Containers belong elsewhere, like specifically a 'Installing
> GNUnet in Docker' section or whatever that can be added later.

Not really. Docker images can be used to get a running GNUnet node instantly.
No worrying about package managers, dependencies et al.
Basically it works just like a VM, but we can easily integrate it into a CI.
Installing is a one liner and it's the same one liner across all platforms.
Regarding maintenance: _If_ we have a CI tool, we can have the images built 
automatically along with the build/tests.
There would be 0 maintenance overhead.

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

Attachment: signature.asc
Description: Message signed with OpenPGP


reply via email to

[Prev in Thread] Current Thread [Next in Thread]