[FM Discuss] State of the english Flossmanuals

andre andre at andrecastro.info
Wed Jun 17 14:56:54 PDT 2015

Sorry to barge in.
I just been lurking for a a couple of months on the floss manuals list and have been a reader for some years(floss
manuals helped me a lot to get into free software). I am grateful to the project and hope I can somehow contribute.

The discussion concerning a more flexible system for writing-publishing-maintaining floss manuals got me interested, so
I'll trow in my 2cents.

At a point in the discussion GitHub was suggested as a possibility.
Although it sounds tempting, as it was already referred, it can discourage less tech minded people from contributing.
But then aren't most of those writing the manuals familiar with git and markdown?
On-the-other-hand using GitHub, seems like a contradiction for a project focused on the dissemination of floss, as
GitHub is not an open source initiative, but a proprietary service, based on Git.

Mediawiki could be another interesting solution.
I allow writing in both wiki syntax or with a WYSIWYG editor, and I believe there are a few plugins that allow the use
of markdown.
It lends itself to a number of editing and publishing workflow, and organizational structure.
The markup can easily and cleanly converted to HTML (epub and Pdf, with so hacks needed for the last).
And includes a very comprehensive web api.

curious where the discussion will head.

On 06/17/2015 10:47 PM, helen varley jamieson wrote:
> i work on the UpStage manual, for which we have (occasionally) had
> contributions from users of the platform who are not at all technical.
> it has been really helpful to be able to involve these people in the
> manual-writing process. in fact the previous FM interface was almost too
> difficult for people to use. keeping it simple for users of software to
> be able to contribute is really important, since users will write quite
> different instructions to those who wrote the software.
> h : )
> On 17/06/15 9:51 28PM, Mick FM wrote:
>> On 17/06/15 19:57, Marvin Scholz wrote:
>>>> I personally don't think it's good for FM as really we want to lower
>>>> barriers to writing docs, so having to use git, or mark up doesn't
>>>> really fit the bill.
>>> Hey, well to be honest I think the opposite is the case. Most people
>>> writing technical
>>> documentation would prefer a markup language like Markdown instead of
>>> a WYSIWG editor.
>> I hear what you are saying there, and I wouldn't dispute it, but let me
>> clarify a bit, I meant that the goal is to make it as easy as possible
>> for *anyone* to write docs without any other technical knowledge.
>>> A lot of sites do a "best of both worlds" solution by having an editor
>>> that has buttons for
>>> most common formatting and inserts the correct Markdown. 
>> Sure, that would be ideal, definitely.
>> And even more ideal if technically able writers could write via markdown
>> and git and others who were less technical could write via a web interface.
>> I think this has already been mentioned on this list but for Booktype
>> 2.0 the Aloha editor is used.
>> http://www.alohaeditor.org/
>> This looks to be a huge improvement!
>> nice one
>> Mick



More information about the Discuss mailing list