[Sugar-devel] Potential volunteer offering technical writing

[Christoph Derndorfer]

On Mon, Oct 31, 2011 at 1:45 AM, Sridhar Dhanapalan
<sridhar at laptop.org.au>wrote:

> On 30 September 2011 19:51, Tabitha Roder <tabitha at tabitha.net.nz> wrote:
> > Hi
> >
> > If we had a volunteer (English Native language) professional technical
> > writer, what writing would be of most use to OLPC or Sugar that we can
> point
> > her in the direction of? She currently works with developers to write end
> > user documentation.
> >
> > Thanks
> > Tabitha - NZ volunteers
>
>
> I think the most important thing is to identify and focus on the
> target audience - is the documentation meant for technical users, end
> users, teachers, children...?
>

That's indeed the key question which we also spent some time discussing in
San Francisco. The current Help activity + corresponding FlossManuals was
mainly written with Give 1, Get 1 users in mind so there's definitely quite
some rework that needs to be done if we're looking to cater to other
audiences.


> We (OLPC Australia) would be happy to suggest ways in which the
> documentation can be improved, using our experience from working
> directly with teachers and communities. Our online course
> (http://laptop.moodle.com.au/ - you can log in as a guest) might
> provide some inspiration.
>

Thanks, I'll take a look:-)


> Our Education Manager has some advice, based on her experiences with
> reading the publicly-available documentation:
>
> -          Make sure the Sugar and XO Floss manuals are up-to-date,
> easily readable and have all the necessary information.
>
> -          Externally available documentation: It’s imperative that
> minimal knowledge is assumed, which I think is the hardest part. Pages
> need to have less information rather than more, good user interfaces,
> lots of useful images, clear headings and language that is simple and
> precise. My concern with a lot of the external documentation is that
> it is sometimes overwhelming, difficult to navigate (both between
> pages and within them) and written for a technical audience rather
> than a basic user. Trying to target both a technical audience and a
> basic user in the same documentation means you are more likely to lose
> the basic user. Perhaps some of this documentation needs to be
> separate out. The main issue I see with the Wiki is that it’s
> difficult to navigate and find information from the menus. This isn’t,
> per say, the role of a technical writer, but tidying up navigation in
> the Wiki would make it more accessible.
>
> -          Someone to simply document the activities available
> (purpose of the activity, how to use it, any tips that are not easily
> discoverable, and what you can DO with it- exemplars of use)
>

That point is also on our agenda:
http://wiki.laptop.org/go/OLPC_SanFranciscoBayArea/OLPCSF_Community_Summit_2011/Help_Activity_Refresh#Revised_Manual_Contents


> -          There are lesson ideas and examples of practice all over
> the place. It would be amazing to synthesise this as much as possible,
> so they are not so difficult and time consuming to find, and to put
> them in a uniform format. I’m not sure what the best way to approach
> this is, but from an educational perspective, knowing not just HOW to
> use the XOs but WHAT to do with them is far more important. Making
> these ideas easily accessible, in my mind, is quite important.


Also something that was discussed various times in San Francisco (and
previously Paris). It definitely sounds like at least Australia, the
Philippines, Jamaica, Madagascar - Nosy Komba, and Austria have some common
needs here which I think we should expand on in a seperate thread. :-)

Cheers,
Christoph

-- 
Christoph Derndorfer

editor, OLPC News [www.olpcnews.com]
volunteer, OLPC (Austria) [www.olpc.at]

e-mail: christoph at derndorfer.eu
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sugarlabs.org/archive/sugar-devel/attachments/20111031/cc5027e1/attachment.html>