[FM Discuss] Discussion about "Bridging the gap between software quality and software education"

[adam hyde]

Its an interesting article Andy. Its a good provocation for discussion
so i will take up the challenge ;)

I do agree with the general point that more strategies for development
of educational material is always a good idea. However, in general I
don't agree with most of the article. There are some broad assertions
that are made but do not seem to carry much support. How can you
assert, for example, that it is "more of a struggle for a project to
provide information than to provide software?". I think providing
software is a huge struggle, one that far exceeds the resources
required to make documentation to support the software.

Also, I have issues with statements like "creating software is fun,
gratifying, and empowering." Seems like a rather massive generalisation
for rather a small sample population, but I make comments about this
below.

And comments like the following I also find a little unsupportable
: "Creating the corresponding educational materials doesn’t generate the
same fizz."

If this was so, why did the OLPC project change its marketing position
to "Its an educational project, not a laptop".

As many faults as there might be with the OLPC project, creating fizz
has not been one of their weaknesses. Education gets fizz. 

However, I leave these for now...I wanted to focus on some other points
that I agree with which at first appear to hold a little more grist.
The point I least agree with is the assertion that people don't enjoy
writing documentation. This is definitely not my experience and indeed
part of my motivation to start FM was to show people that writing docs
can be fun and rewarding. I think we have, as a community, proven that
point, not just in the Book Sprint environment but also with writing
docs on a day to day basis. I field feedback every week now from people
who love contributing to FM. You can also see the enthusiasm on the
list. These people obviously enjoy it. I also enjoy writing docs. 

The Book Sprints are a particularly shining example of people enjoying
writing docs. I had many positive emails about the last sprint (Open
Translation Tools), but these are the ones coming to a public list
(OTT09) that I can republish :

"I must say that participating in the book sprint was one of the most
fascinating, experiences I have ever had...I am still digesting all this
information and this book will most definitely be a useful tool for not
only the “open” world, but I think the “traditional” world will learn
quite a bit as well."
Ed Zad, Director of Operations and Language Services, Dot Sub

from a remote participant :
"Fantastic work, all of you amazing book sprinters!  Heroic!!  This is a
wonderful resource for the world of open translation.Okay, I have to go
forward the URL to everyone now :)"
Dr. Laura Welcher, The Long Now Foundation, Director of Development and
The Rosetta Project

and another remote participant :
"Unbelivable! I just popped by the Floss Manual website to take a look
at the work the book sprint folks have been doing on the Open
Translation Manual. I am amazed; wonderful work everyone. I am so
looking forward to reading it more closely. You all must be elated and
exhausted."
Petra Timmermans
Coordinator, ICRSE

I have others but these make the point. 

Each of these people contributed. They seemed to enjoy the process and
be enthusiastic about it.

However I think most of all I want to make the point that if people did
not enjoy writing docs we simply would not exist. The fact that we have
so many docs and of such high quality and we are attracting more and
more people every day (we now have 800 members on the english site -
thats +100 in the last month, and 200-300 in the translation and
non-english sites, 200 on this list), seems to me to suggest that not only do people enjoy
writing docs, but they enjoy it a lot.

So I don't really understand why Ed might say  "Perhaps we have not
recruited enough of the right people yet." as I think we _have_
'recruited' enough people to illustrate that doc writing is an
enjoyable experience. Others enjoy the experience as much as Ed and I
do, that's clear.

However, I think Ed and you are trying to ask another question - the
question should not actually be framed as "why dont people enjoy
writing docs" (which I think is fundamentally false) but "why are there
so few people writing docs in comparison to the number of people making
free software". 

This is an interesting question, however it is a question that should
be asked about open content in general not just to free documentation.
Why, for example, did Creative Commons, specialising in the promotion
of open content, just catch on in the last 3 years or so, many many years
after the free software sector was well established? A very very
interesting question but not one I think can be answered by simply
saying "because people dont enjoy creating content".  Why the free
software sector has flourished and open content hasnt (until recently)
is an interesting question but I think it is a mistake to see this as a
issue unique to free documentation. 

We should not conclude that creating open content is not enjoyable or
rewarding just because there has been little activity in this area in
the past. Instead we should be celebrating that now things are
changing. We are seeing more open content communities emerge and we are
just one example within this emergent field. Open content communities
are catching on. Wikipedia obviously led the charge and we are many
years behind but doing a good job none the less. 

So, if the point of your article Andy is "how do we bridge the gap".
My response would be very simple - its already happening. 

As for the challenges that face FM - I am always interested in
discussing these. However I don't actually understand from the article
what you think these challenges actually are. If you can say more about
what challenges lay in our path now I would be very keen to get these
out in the open and onto this list. This is an invitation to anyone,
anytime of course. 

Lastly, I would like to challenge the seemingly unchallengeable
position that people enjoy writing software. Many people do not and so
they don't. Anecdotally - I have seen many people claim recently the
popularity of contributing to free software projects has declined. I
can't really comment on this but I can talk from my own experience as a
programmer. I wrote some softwares years ago, I didn't enjoy it. It was
painful, boring, and I didn't find it always rewarding even though the
softwares were successful in their field. I hated fielding bug
reports, I hated rewriting the software as most software projects
inevitably do, I hated the long development paths for complex
components. It was not fun. So now I don't do it anymore. 

Now, when software development needs to happen for FM I prefer to work with
people that do like writing software and do a far better job than I
ever could.

Then I open the browser and click 'edit'...

adam








On Mon, 2009-07-06 at 21:14 -0700, Edward Cherlin wrote:
> On Mon, Jul 6, 2009 at 6:46 AM, Andy Oram<andyo at oreilly.com> wrote:
> > I'm working on a new article that challenges the work of FLOSS Manuals. We've clearly recruited a lot of people and have a lot of projects going. But when I use new software and check out the documentation, I get the sense something different is needed. The following is just a draft:
> >
> > http://www.praxagora.com/andyo/draft/education_scope.html
> 
> Interesting.
> 
> You say that it takes longer to produce documentation than software.
> This is the opposite of my experience as a tech writer, where I was
> routinely expected to write up several months programming work in a
> week or two. You are right that producing a publishable book takes
> more effort, but we have the sprints for that, giving us the
> combination of numbers and speed.
> 
> "People _enjoy_ creating software. They don’t enjoy creating
> documentation or educational materials as much. " Perhaps we have not
> recruited enough of the right people yet. I certainly enjoy
> documentation, and I have observed many others enjoying our sprints.
> 
> I see later in your article that you and Adam discussed this.
> 
> FAQs, Wikis, and so forth, good resources.
> 
> Quizzes +1
> 
> Quizzes give the user an idea of how much he/she does and does not
> know, and about what. We should have a preliminary overview that can
> be taken as a quiz or just a set of bullet points, depending on the
> attitude of the reader. We should have at least one, possibly several
> quizzes for afterward, so that readers can tell how much they have
> learned, and whether they missed something.
> 
> We will need to test any quizzes we create, asking whether we are
> testing what is important to our readers, and whether they can tell
> what to do about questions they miss.
> 
> I would add to your list writing articles, blog posts, and so on when
> we discover that the community knows something significant to the work
> that prospective members don't, whenever tha would motivate them to
> join in or help them to get started.
> 
> > I also went on the FM IRC channel with the request for discussion.
> >
> > Andy
> > _______________________________________________
> > Discuss mailing list
> > Discuss at lists.flossmanuals.net
> > http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
> >
> 
> 
> 
-- 
Adam Hyde
Founder FLOSS Manuals
German mobile : + 49 15 2230 54563
Email : adam at flossmanuals.net
irc: irc.freenode.net #flossmanuals

"Free manuals for free software"
http://www.flossmanuals.net/about