[Sugar-devel] Flossmanuals?

[Bastien]

Hi David, Luke and all,

David Farning <dfarning at sugarlabs.org> writes:

> Have you pinged the FM mailing list at
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net .
> They are usually pretty helpful.

Lionel did, they replied but couldn't solve this encoding issue.

> The biggest reason for leaning on FM is that they have a good
> reputation for creating usable end user documentation.  

Yeah, fair enough.  

My first concern was about writing "portable" documentation.  After
hours of sweating while trying to clean up the HTML files produced by FM
in order to integrate those files into the HelpFr activity, I thought
"Phew... all this would have been much easier if we had written this in
a wiki!"

Hence my first question.

But now my real concern is about encouraging activity writers to write
documentation that is browsable from within Sugar.  The Help activity is
both useful and adhoc.  The help should be linked very closely to the
activity, and I think the FM format keep developers far from this goal.

> Traditionally,
> documentation is one of the weakest parts of open source projects,
> because no one every gets around to writing it.

But what is the prefered format for good documentation?  Plain text.
HTML.  Man page.  Texinfo pages.  DocBook.  Wikis.  Things that can 
be easily manipulated and exported...

> Unless someone really motivated and really talented comes on board, I
> don't SL being able to create the quality of content FM creates in the
> near term.

My guess was that SL content on FM was created by the SL community 
(in "documentation sprints") -- not by the FM community.  But if the 
FM community is contributing to SL doc a lot, so far so good, let's 
stick to this way of working.

Anyhow, I still have this feeling: if I were a teacher, the FM manuals
would look like "official manuals", writings that is produced top-down
for me and I don't need to contribute, even if I have something useful
to write...  Maybe that's the purpose, I don't know.

> I think there are about 10 translations of the Sugar manuals in
> various states.

Can't see them..  where are they?

Thanks!

-- 
 Bastien