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

Tue Jul 7 07:20:20 PDT 2009

Yes, let's not perpetuate the myth that "technical writing is boring." Most
certainly it is not, although apparently Tom Johnson gets that question
quite often. He has a discussion here:
http://www.idratherbewriting.com/2007/02/13/is-technical-writing-boring/.
Lots of discussion ensued.

Personally, I can't say it's "fun" all the time, but I can say it's
enjoyable when you're working with good people using tools that help you
infuse feedback and continual improvements that truly help people. I'm
motivated by time savings, efficiency, altruistic intentions, attention
generation, and so on. Likely the same motivations are in play for actually
writing the software - though often the software was written to solve a
basic problem (Apache to serve web pages). My point was that writing
documentation can solve a few different problems, and "education" may be too
broad.

Thanks for the thought-provoking article!
Anne

 *Anne Gentle*
annegentle at justwriteclick.com my blog <http://justwriteclick.com> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
del.icio.us<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>

On Tue, Jul 7, 2009 at 6:32 AM, adam hyde <adam at flossmanuals.net> wrote:

> 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
>
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20090707/ef980441/attachment.htm>