Work in progress - documentation (and suggestions)

[Tiago Saboga]

Hi!

As I said before, I am working on gathering information about
gitenberg and collecting it all in a unique place.

It was a lot more difficult than I thought, because it is all really
scattered all around and I work on a very slow internet connection,
but I think there is some progress. You can see my updated version of
the wiki on my fork of the wiki:

https://github.com/tiagosab/wiki/wiki

And now I have lots of questions and a couple of suggestions.

First of all, directly related to this work on the wiki, I suggest
abandoning the github wiki and working directly on the wiki repo
(which could be, btw, renamed to something else, like
gitenberg-doc). The main reason for that is to allow using the regular
github workflow, with pull requests, which are not implemented on the
wiki part of the site.

My second suggestion is to find alternatives to google groups to host
this mailing list. I had a really hard time with a slow connection to
read all of the list - and it still is a very young and short list. I
think that a project that intends to deliver free and open means to
access free and open data should not rely on a provider which does not
allow a minimum of freedom. The use of github is a matter of some
concern, too, but I think the limit is not being locked in. And it is
the case with google groups: there is no way - except web scraping -
to get all the past list messages to archive somewhere else. I am sure
we could find a host for a mailing list - we could approach debian's
alioth, or fsf's non-gnu savannah, for instance.

I'll keep my questions for later, have to go to work ;(

Cheers,

Tiago

[Seth Woodworth]

Thank you Tiago!  I will reply in-line:

On Tue, Mar 24, 2015 at 8:19 AM, Tiago Saboga <tiago...@gmail.com> wrote:

It was a lot more difficult than I thought, because it is all really
scattered all around and I work on a very slow internet connection,
but I think there is some progress.

Sorry about that, and thank you for writing up this documentation.  

I too am concerned about access to the project and will 

 

You can see my updated version of
the wiki on my fork of the wiki:

https://github.com/tiagosab/wiki/wiki

Clever application.  FYI for everyone else.  Github wikis can be cloned via github.com/gitenberg-dev/<reponame>/wiki.git.

And now I have lots of questions and a couple of suggestions.

First of all, directly related to this work on the wiki, I suggest
abandoning the github wiki and working directly on the wiki repo
(which could be, btw, renamed to something else, like
gitenberg-doc). The main reason for that is to allow using the regular
github workflow, with pull requests, which are not implemented on the
wiki part of the site.

100% agree.  We can't keep the activerepos.csv in the wiki, and since that file is there, it makes sense to put the docs for adding books to the spreadsheet in the parent repo.  This means some docs are at gitenberg-dev/wiki and some docs are at gitenberg-dev/wiki/wiki.  Not a good solution.

Furthermore, we can host the docs on our upcoming website (django source for new website).

 

My second suggestion is to find alternatives to google groups to host
this mailing list. I had a really hard time with a slow connection to
read all of the list - and it still is a very young and short list. I
think that a project that intends to deliver free and open means to
access free and open data should not rely on a provider which does not
allow a minimum of freedom.

Google groups was easy/fast to set up.  I am willing to migrate.

The Internet Archive has hosted lists for other book projects I've worked on via their Mailman install.

I expect they would be willing to host a list for this project.  I will ask!

 

The use of github is a matter of some
concern, too, but I think the limit is not being locked in.

Github is a mixed bag.  A number of things are broken on github when we have this many repos.

Git allows for relatively easy forking of the entire project IMO, so I don't feel like we have too much lock-in if it would behoove us to migrate.  OTOH, github allows for a huge surface area for folks to find the project and hopefully contribute (even by reporting book issues).

Anish Mangal brought up using Gitlab as an offline cache of GITenberg.  He is working on a One Laptop per Child deployment in Bhagmalpur, India.  At a minimum I would like GITenberg having a separate git mirror.  The tools for creating this mirror (probably with Gitlab) would be the same tools for someone to create their own offline mirror of GITenberg.

Tl:DR;  I am 100% on board.  

I've created gitenberg-dev/documentation. I will merge your wiki fork branch, merge the activerepos.csv file and retire wiki/wiki later today.

[Tiago Saboga]

On Tue, Mar 24, 2015 at 10:00 AM, Seth Woodworth <se...@sethish.com> wrote:
> Thank you Tiago! I will reply in-line:

Inline we go.

> On Tue, Mar 24, 2015 at 8:19 AM, Tiago Saboga <tiago...@gmail.com> wrote:
>>
>>
>> It was a lot more difficult than I thought, because it is all really
>> scattered all around and I work on a very slow internet connection,
>> but I think there is some progress.
>
> Sorry about that, and thank you for writing up this documentation.
> I too am concerned about access to the project and will

Nothing to be sorry about...

>> And now I have lots of questions and a couple of suggestions.
>>
>> First of all, directly related to this work on the wiki, I suggest
>> abandoning the github wiki and working directly on the wiki repo
>> (which could be, btw, renamed to something else, like
>> gitenberg-doc). The main reason for that is to allow using the regular
>> github workflow, with pull requests, which are not implemented on the
>> wiki part of the site.
>
>
> 100% agree. We can't keep the activerepos.csv in the wiki, and since that
> file is there, it makes sense to put the docs for adding books to the
> spreadsheet in the parent repo. This means some docs are at
> gitenberg-dev/wiki and some docs are at gitenberg-dev/wiki/wiki. Not a good
> solution.
>
> Furthermore, we can host the docs on our upcoming website (django source for
> new website).

Perfect!

>>
>>
>> My second suggestion is to find alternatives to google groups to host
>> this mailing list. I had a really hard time with a slow connection to
>> read all of the list - and it still is a very young and short list. I
>> think that a project that intends to deliver free and open means to
>> access free and open data should not rely on a provider which does not
>> allow a minimum of freedom.
>
>
> Google groups was easy/fast to set up. I am willing to migrate.
>
> The Internet Archive has hosted lists for other book projects I've worked on
> via their Mailman install.
> I expect they would be willing to host a list for this project. I will ask!

Great!

>>
>> The use of github is a matter of some
>> concern, too, but I think the limit is not being locked in.
>
>
> Github is a mixed bag. A number of things are broken on github when we have
> this many repos.
> Git allows for relatively easy forking of the entire project IMO, so I don't
> feel like we have too much lock-in if it would behoove us to migrate. OTOH,
> github allows for a huge surface area for folks to find the project and
> hopefully contribute (even by reporting book issues).

You mean one can fork all gitenberg repos at once? How?

> Anish Mangal brought up using Gitlab as an offline cache of GITenberg. He
> is working on a One Laptop per Child deployment in Bhagmalpur, India. At a
> minimum I would like GITenberg having a separate git mirror. The tools for
> creating this mirror (probably with Gitlab) would be the same tools for
> someone to create their own offline mirror of GITenberg.
>
>
> Tl:DR; I am 100% on board.
>
> I've created gitenberg-dev/documentation. I will merge your wiki fork
> branch, merge the activerepos.csv file and retire wiki/wiki later today.

Ok, I will fork it soon ;)

Tiago

[Tom Morris]

On Tue, Mar 24, 2015 at 10:00 AM, Seth Woodworth <se...@sethish.com> wrote:

Thank you Tiago!  I will reply in-line:

On Tue, Mar 24, 2015 at 8:19 AM, Tiago Saboga <tiago...@gmail.com> wrote:

First of all, directly related to this work on the wiki, I suggest
abandoning the github wiki and working directly on the wiki repo
(which could be, btw, renamed to something else, like
gitenberg-doc). The main reason for that is to allow using the regular
github workflow, with pull requests, which are not implemented on the
wiki part of the site.

100% agree.  We can't keep the activerepos.csv in the wiki, and since that file is there, it makes sense to put the docs for adding books to the spreadsheet in the parent repo.  This means some docs are at gitenberg-dev/wiki and some docs are at gitenberg-dev/wiki/wiki.  Not a good solution.

Editing a wiki is a much lower barrier to entry for a contributor than learning how to manage git and make pull requests.  If you would like non-geeks to contribute, it's something to keep in mind.

 

My second suggestion is to find alternatives to google groups to host
this mailing list. I had a really hard time with a slow connection to
read all of the list - and it still is a very young and short list. I
think that a project that intends to deliver free and open means to
access free and open data should not rely on a provider which does not
allow a minimum of freedom.

Google groups was easy/fast to set up.  I am willing to migrate.

The Internet Archive has hosted lists for other book projects I've worked on via their Mailman install.

I expect they would be willing to host a list for this project.  I will ask!

Mailman?  Ugh!  Talk about a mail archive interface from the 80s.  And the Internet Archive rivals Google for insularity and lack of transparency, but I think choosing tooling based on perceived political considerations to be lower priority than making sure the team has what it needs to work efficiently.

Why not just use MarkMail or Mail Archive to provide an easily searchable archive of the mailing list?

Tom

[Tiago Saboga]

On Tue, Mar 24, 2015 at 3:15 PM, Tom Morris <tfmo...@gmail.com> wrote:
> On Tue, Mar 24, 2015 at 10:00 AM, Seth Woodworth <se...@sethish.com> wrote:
>> 100% agree. We can't keep the activerepos.csv in the wiki, and since that
>> file is there, it makes sense to put the docs for adding books to the
>> spreadsheet in the parent repo. This means some docs are at
>> gitenberg-dev/wiki and some docs are at gitenberg-dev/wiki/wiki. Not a good
>> solution.
>
> Editing a wiki is a much lower barrier to entry for a contributor than
> learning how to manage git and make pull requests. If you would like
> non-geeks to contribute, it's something to keep in mind.

I do not think the project is really at a point where "non-geeks" are
a really valuable resource. The central idea is moving Gutenberg data
to a version controlled system, and assuming some familiarity with the
choosen system does not seem illogical at this point - and this is
gitenberg*-dev* documentation, not end user gitenberg documentation.

>>>
>>> My second suggestion is to find alternatives to google groups to host
>>> this mailing list. I had a really hard time with a slow connection to
>>> read all of the list - and it still is a very young and short list. I
>>> think that a project that intends to deliver free and open means to
>>> access free and open data should not rely on a provider which does not
>>> allow a minimum of freedom.
>>
>>
>> Google groups was easy/fast to set up. I am willing to migrate.
>>
>> The Internet Archive has hosted lists for other book projects I've worked
>> on via their Mailman install.
>> I expect they would be willing to host a list for this project. I will
>> ask!
>
>
> Mailman? Ugh! Talk about a mail archive interface from the 80s. And the
> Internet Archive rivals Google for insularity and lack of transparency, but
> I think choosing tooling based on perceived political considerations to be
> lower priority than making sure the team has what it needs to work
> efficiently.

One could also take your "from the 80s" argument to be a "perceived
political consideration". I, for one, have had obstacles to work
efficiently using google groups, and I have voiced it.

The argument about insularity and lack of transparency stand on its
own, but I have no comments on that, as I do not know IA.

> Why not just use MarkMail or Mail Archive to provide an easily searchable
> archive of the mailing list?

One important point to me, that I do not take as "perceived political
consideration", is the possibility to take out the data produced. I
need it now, because I cannot afford having to browse a web site every
time I have to re-read some group message, but more importantly it
should be kept even if the provider decides to stop providing the
service. In fact, I think I would be fine just having the list mails
forwarded to Mail Archive.

Cheers,

Tiago

[Roger Sperberg]

Are GitHub issues an insufficient replacement for mailing-list threads?

--
You received this message because you are subscribed to the Google Groups "GITenberg Project" group.
To unsubscribe from this group and stop receiving emails from it, send an email to gitenberg-proj...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/gitenberg-project/CAPZMwhQk3hy3tn23DYO2veh8W3mRGgRsC86MYHkBkxo-9JuP3Q%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Roger Sperberg
Montclair, NJ 07043

973-200-4224
--
rsperberg at gmail

@RogerSPress

github.com/rsperberg

linkedin.com/in/rsperberg

JavaScript certified at bloc.io

web development track at

[Seth Woodworth]

I have:

+ pulled your fork of the wiki

+ merged it with the extra `activerepos.csv

On Tue, Mar 24, 2015 at 10:00 AM, Seth Woodworth <se...@sethish.com> wrote:

[Seth Woodworth]

Whoops!

I have:

+ pulled your fork of the wiki.wiki

+ merged it with the `activerepos.csv` repo

+ pushed them both to the documentation repo

+ retired the old wiki

It will be a simple process to build this repo as a collection of asciidoc articles and put it on a website.  But in the meantime, it is editable and viewable via github.

[Seth Woodworth]

Why not just use MarkMail or Mail Archive to provide an easily searchable archive of the mailing list?

Excellent suggestion.  I gave it a shot.  I can't figure out how to add lists to MarkMail, and Google wont allow the archive@mail-archive address to sign up for any more google groups.  I'll have to try another service.

--S

[Eric Hellman]

Does anyone have experence of other vaguely similar projects and can share what has worked well in the beginning stages of a project?

Free-programming-books, for example, does everything in github issues.

Distributed Profreaders does everything in forums, but they also have a private developers list,

I've seen projects have huge Google Hangouts. we could do that.

I have all the google groups messages on my laptop and I can send an archive, if that's useful.