[Help-smalltalk] [PATCH] doc: fix typo in tutorial.texi

[Alex Jordan]

Heya!

I'm attaching a patch that fixes a typo I found while going through
the tutorial. The problem was "passed arguments ments" instead of
"passed arguments" but when I did M-q in Emacs to wrap lines, it
reformatted the whole paragraph. Hence the larger diff. I'm not sure
if it's formatted correctly (see waaaay below), so feel free to mangle
my patch and commit it, ignore my patch and just commit the fix
yourselves, etc.

As a side note, I found a typo on the website: the sentence under
ChangeLog on http://smalltalk.gnu.org/development/contributing is
missing a period. Can't find the source to the website though, so no
patch.

Also, I gotta say this: GNU Smalltalk is by far the hardest free
software project to contribute to I've ever encountered. Please take
this as constructive criticism, as I'm only trying to help get you
more contributors. But drive-by patches like this one are a ridiculous
amount of work:

1. I can't find how to contribute from the front
   page. http://smalltalk.gnu.org/ links to
   http://smalltalk.gnu.org/development, but this page doesn't
   actually help because it tells me nothing practical about how to
   contribute (at least for drive-by patches like this one). The only
   practically useful thing for me was the mention of git (the link
   for which, btw, is out-of-date and redirects to git-scm.com). But
   from this page it wasn't immediately obvious where I could get git
   sources. At the very least this page needs to link to pages I
   mention in items 2 and 3, but ideally all of this information would
   just be consolidated on a single page.

2. After a minute of looking around (bearing in mind that someone less
   familiar with contributing to free software _already_ would've
   given up), I found http://smalltalk.gnu.org/download/cvs. This page
   tells me where to clone the repositories from, but tells me nothing
   about where to actually send patches. Also, a number of places on
   the website say things like:

   > By setting up your own public repositories for GNU Smalltalk
   > branches (for example at http://git.or.cz), you will facilitate
   > integration of your code into the main distribution.

   This is really confusing and jargon-y, and people new to free
   software just won't get this. You should phrase this as something
   like:

   > It will help the GNU Smalltalk developers integrate your changes
   > faster if you publish your local development copy somewhere, as a
   > git repository that they can clone to their machines.

3. After several more minutes of poking around the website, I found
   http://smalltalk.gnu.org/development/contributing. This page seems
   to say that GNU Smalltalk uses a traditional "mail your patch"
   workflow, but that workflow just doesn't make sense to people new
   to free software. Not only will they not know how to do that, they
   probably won't even have any idea what they're *supposed* to do,
   because this page just assumes the reader is already familiar with
   this workflow.

   Even I had difficulty with these instructions, and I'm already
   pretty familiar with sending patch files around. Why is this page
   talking about using `diff`? I didn't use `diff` to generate my
   patch - why would I when I have a fully functional git clone I've
   just committed to? I used the right/natural tool for the job (`git
   format-patch`) and consequently I have no idea if I obeyed the
   request to use the `-up` options.

   By far the most egregious requirement on this page is the way you
   have to attach patches to mail messages. Why in the world can I not
   attach a patch with disposition "attachment", and why do I have to
   change the MIME type? Is it just for purity? Who cares?

   Lots and lots of people will have no idea what this means and will
   give up because they don't care enough. Still more people (like
   myself) will have a vague idea what it means, but will have no idea
   _how_ to actually do that in their mail client. Probably lots of
   clients simply don't even have options for these things.

   Preferably the "mail your patch" workflow would be replaced by a
   Pull Request-style workflow (or even a "just point us to a branch
   on a public clone" workflow) but if that isn't going to happen,
   these instructions should still just go away.

4. After all that, you have to send a message to a mailing list that's
   _subscriber only_. Seriously? I just want to send a typo fix. I
   don't want to subscribe to the Smalltalk mailing list, which is a
   lot of work and will send me email I won't read. If you don't want
   to allow *all* mail through, just make mailing list have a
   moderation queue. Easy fix. (Assuming you _must_ stay on the
   current "mail a patch" workflow which again, is very unideal.)

Again, I hope this is seen as constructive criticism, not
complaining. I'm sure there are reasons for a lot of the things I
named above, but that doesn't change the fact that people, especially
new contributors, aren't going to bend over backwards to contribute to
GNU Smalltalk. If anything it should be the other way around, where
the project does everything it can (within reason) to make it easy to
get new contributors.

Think of it as a long term investment: it'll be some work up front,
but in the long run you'll have more people part of the community,
critiquing and generating ideas and code and doing all the other stuff
that active community members do. But this only works if you make it
easy to start with, before they're committed to the project. If you
ask them to do a bunch of work before they've even decided Smalltalk
is worth spending time on, they just won't care.

I hope this is useful.

Please CC me if you need to on replies, as I will be unsubscribing
from this mailing list as soon as this message goes through.

Cheers,

AJ

signature.asc
Description: PGP signature