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

[Edward Cherlin]

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
>



-- 
Silent Thunder (默雷/धर्ममेघशब्दगर्ज/دھرممیگھشبدگر ج) is my name
And Children are my nation.
The Cosmos is my dwelling place, The Truth my destination.
http://earthtreasury.org/worknet (Edward Mokurai Cherlin)