Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
Schanzenbach, Martin transcribed 10K bytes: > > > > On 3. Jun 2018, at 22:33, Nils Gillmann wrote: > > > > Hi, > > > > Schanzenbach, Martin transcribed 6.5K bytes: > > 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. We are in a good number of Operating Systems. The number can still grow, but it's more than 3. I'll reply to the rest later. ___ GNUnet-developers mailing list GNUnet-developers@gnu.org https://lists.gnu.org/mailman/listinfo/gnunet-developers
Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
> On 3. Jun 2018, at 22:33, Nils Gillmann 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 wrote: >>> >>> Nils Gillmann transcribed 1.7K bytes: en3r0 transcribed 3.8K bytes: > Hi Nils,
Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
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 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 > >
Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
Hi,
my 2 cents on the Installation Handbook:
I actually thing that installing from source is not something the average joe
should have to do.
Ideally there is an installer package (MSI,dmg/pkg,.deb/.rpm).
Alternatively (and temporarily until we are in alpha/beta), we could provide a
docker image (maybe we get a project account there and integrate the build into
our future CI) then it is as simple as a "docker run gnunet:latest".
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.
With that in mind, the Installation Handbook can assume the reader is quite
savvy.
BR
Martin
> On 3. Jun 2018, at 20:54, Nils Gillmann 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 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
>> GNUnet-developers@gnu.org
>> https://lists.gnu.o
Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
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 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
> GNUnet-developers@gnu.org
> https://lists.gnu.org/mailman/listinfo/gnunet-developers
___
GNUnet-developers mailing list
GNUnet-developers@gnu.org
https://lists.gnu.org/mailman/listinfo/gnunet-developers
Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
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.
>
> 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 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
GNUnet-developers@gnu.org
https://lists.gnu.org/mailman/listinfo/gnunet-developers
Re: [GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
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. 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 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" > > ___ > GNUnet-developers mailing list > GNUnet-developers@gnu.org > https://lists.gnu.org/mailman/listinfo/gnunet-developers > ___ GNUnet-developers mailing list GNUnet-developers@gnu.org https://lists.gnu.org/mailman/listinfo/gnunet-developers
[GNUnet-developers] documentation: Rewriting the Installation Handbook with a focus on simplicity and coverage
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" ___ GNUnet-developers mailing list GNUnet-developers@gnu.org https://lists.gnu.org/mailman/listinfo/gnunet-developers
