[FM Discuss] ars entry - first attempt

Mon Mar 17 15:24:43 PDT 2008

here are my suggestions.

..on or around Tue, Mar 11, 2008 at 04:01:35PM -0400, adam hyde said:
> below is my first attempt. we have 8 days to improve it. We can also
> upload an extra document about the project and all its facets.
> 
> any suggestions on improvements are very welcome.
> 
> ---------------------
> 
>  
> * Titel / name of the project:  FLOSS Manuals
> 
> * Type of project:  Community-Projekt
> 
> * Description of the project:  FLOSS Manuals is a community of free
> documentation writers. We write manuals about how to use free software.
> Largely the manuals are written by artists who have a great deal of
> experience with free software and often have experience leading
> workshops on these technologies.

the use of 'Largely' and 'often' sounds a little lacking in confidence.
this is normally fine but not in an introduction. i'd be more assertive
and say "The manuals are written by.." and "..  with free software and
have experience leading.."/

> 
> In addition more and more developers are looking to FLOSS Manuals to be
> the repository and community to develop the documentation for their
> projects. One Laptop Per Child and Inkscape are both utlising the FLOSS
> Manuals toolkits and interacting with the community to build and improve
> their docs.

above line contains grammatical ambiguities. try:

	Increasing numbers of developers are looking to FLOSS Manuals as an
	important repository in the development of the documentation for their
	projects. Communities like One Laptop Per Child and Inkscape are both
	utlising the FLOSS Manuals toolkits and interacting with the community
	to build and improve their docs.

> 
> * URL of the project:  http://www.flossmanuals.net
> 
> * Objectives:  Our main objective is to increase the uptake of free
> softwares through the provision of excellent free documentation.

'softwares', while correct, looks like a typo to most eyes. words like
'provision' look a bit posh. try:

	* Objectives:  Our main objective is to increase the uptake of free
	software by providing high quality free documentation.

> 
> * Language and context:  We are a distributed international community.
> Currently we are extending into Farsi and Bengali communities with the
> development of localised FLOSS Manuals sites and communities in each
> language.

'Currently' doesn't work well as a sentence opening i think.
'communities' appears twice in one sentence also. looks forced. sentence
way too long try:

	 * Language and context:  We are a distributed international
	 * community.

	 As an example of our efforts to internationalise, we are currently
	 extending documentation into the Farsi and Bengali languages. We
	 are doing this by developing sites and communities localised in
	 each language.

> 
> * Project history:  The project was launched in October 2007.
> 
> FLOSS Manuals genesis began in 2004 when Adam Hyde from r a d i o q u a
> l i a (http://www.radioqualia.net) put his workshop notes online for his
> teachings on free software tools for streaming media. After this,
> through a residency with MAMA (New Media Lab, Zagreb) Adam put all the
> content in a wiki so he could update it (2006). In 2007 this wiki
> (TWiki) was extended with custom plugins for FLOSS Manuals so it could
> be a collaborative authoring platform for free documentation on free
> software. The official launch was in Amsterdam, October 2007.
> 
> * Involved People:  There is a wide community of writers and they focus
> on one or more documentation projects within FLOSS Manuals. We have, for
> example, artists like Julian Oliver (http://www.selectparks.net), Derek
> Holzer (http://www.umatic.nl) and Sophea Lerner (http://phonebox.org)
> heading the Blender, PureData and Audacity manuals.
> 
> Alongside this the official documentation teams from the One Laptop per
> Child and Inkscape (free software vector graphic program) use FLOSS
> Manuals for creating the 'official' documentation for their projects.
> 
> Most people involved are either new media artists that use free
> software, or free software advocates and enthusiasts that see better
> documentation as the key to the increased uptake of free software in the
> desktop.
> 

the above is all pretty good i reckon.

> * Lessons learned:  We mix voluntary and paid contributions and this
> works very well although it is usually frowned on by other 'free
> culture' projects. We intend to find away where payments are possible
> but not always required. In this way we build and maintain experience
> within the organisation.

hmm, a few too many 'ands'. try:

	* Lessons learned:  We mix voluntary and paid contributions. This
	works very well although it is sometimes frowned upon by other 'free
	culture' projects. We intend to find a way where payments are
	possible but not essential to inviting contributions. In this way we
	build and maintain experience within the organisation.

> 
> Also, our platform surpasses anything available as a platform for
> collaborative authoring of books. We have created many tools that turn
> TWiki into a authoring platform from which we can output digital and
> books (via print on demand).
> 

begins with 'Also' and 'platform appears twice. assumes people know
that TWiki is a software (readers are lazy). s/a/an needed also.
'output' is ambiguous.

	We believe our platform surpasses any other in the collaborative
	authoring of books. We have created many tools that have transformed
	the popular TWiki software into a fully capable authoring platform
	from which books can both be created and distributed. Books written
	using our platform can be published online and in 'hard copy', via
	our print on demand service.

> So far nothing has 'not worked'.

	So far we have enjoyed great success as a publishing and
	distribution platform.

> 
> * Technological basis:  We are an all GPL system. We are built on TWiki,
> and we develop customised plugins that we feed back into the TWiki
> repository.

assumes reader knowledge of the 'GPL'.

	* Technological basis:  The FM platform uses software released under
	the General Public Licence, encouraging public improvement of the
	tools we use. We chose to use the popular WIKI software 'TWiki',
	upon which we've built special plugins. In the spirit of the GPL,
	these plugins are shared back into the public TWiki repository for
	others to use in the own authoring projects. 

> 
> All coding is in perl although we are currently using python for a PDF
> formatting module. This will tie FLOSS Manuals directly into print on
> demand so that books can be published and available for purchase after
> one click.

assumes knowledge of what 'perl' is. try: 

	All programming was done in the language Perl, although we are
	currently using another scripting language Python for a PDF
	formatting module. This will tie FLOSS Manuals directly into print
	on demand so that books can be published and available for purchase
	as a 'one click' service.

> 
> We currently output to downloadable PDF and online HTML.
> 
> It is also possible to remix (http://www.flossmanuals.net/remix) content
> to make your own manuals from available content. This means you can
> create lovely PDF, or downloadable HTML (with your own CSS) through a
> simple drag and drop process.

	It is also possible to remix (http://www.flossmanuals.net/remix)
	content to create customised manuals from existing content. Content is
	made using a simple drag-and-drop process and can then be published
	as either a beautifully rendered PDF document or as downloadable,
	stylised HTML documents.

> 
> Additionally we have a 'Live Manual' api which enables you to embed your
> remixed manual into any webpage, CMS, or Blog by cutting and pasting 5
> lines of HTML.

	Additionally, we have a 'Live Manual' Application Programmers
	Interface which enables users to embed their remixed manual into any
	webpage, CMS, or Blog by simply cutting and pasting 5 lines of HTML
	code.
> 
> we have done tis on a shoe string and the functionality exceeds anything
> else available.

many second language english speakers have no idea what a 'shoe string'
budget is. i speak from experience having tried to use that phrase ;)

	We have done this on a very small budget, yet we believe the
	functionality exceeds anything else available.

> 
> * Solutions:  The solution is inpart a software solution. We have built
> plugins to turn a wiki into a publishing system, suited for
> collaborative authoring and outputting to multiple sot and hard copy
> formats. There is nothing like this available until now. Most
> importantly we have developed copyright tracking functionality for
> appropriate accreditation of contributions, and index manager for
> determining the sequence of chapters via a simple drag and drop process,
> sophisticated output to PDF, and the ability to remix any content to
> make your own document.

	* Solutions:  The FM solution comes in the form of a software tool
	that we believe fills a vital gap in the publishing and distribution
	of quality, free, technical manuals. 

	We have built many plugins that transform a wiki software into a
	fully capable publishing system, suited for collaborative authoring
	and output to both digital and hard-copy formats. Until FM, there
	was nothing of this kind available for those that wanted to freely
	publish manuals.. 

	Other solutions include the development of a 'copyright tracking'
	functionality to ensure the appropriate accreditation of
	contributions, an index manager for determining the sequence of
	chapters via a simple drag and drop process, sophisticated output to
	PDF and the ability to remix any content to make your own document.
> 
> 
> The Live Journal API is entirely innovative. Nothing exists to parallel
> it. It enables anyone to embed full manuals in their own webpage or blog
> through the pasting of 5 simple lines of HTML.
> 

the above trumpet-blows a bit too much. i'd tone it down a bit..

> All these plugins we have released as GPL.

	All the plugins we've authored have been released under the
	General Public Licence.

> 
> * Implementations:  We have English manuals, and Dutch Manuals. On the
> horizon is a complete site in Farsi, and then we move t the
> implementation of a Bengali site.

	* Implementations:  We currently have English and Dutch Manuals.
	Coming soon is a complete site in Farsi after which point we begin
	the implementation of a Bengali site.
> 
> * Users:  Anyone that has a need for desktop software is a potential
> user.
> 
> * License:  All technologies are available via GPL. In addition, all
> content is available under GPL (GPL is a content license too, please
> see : http://www.gnu.org/philosophy/nonsoftware-copyleft.html
> 
> * Statement of Reasons:  With 60% of all websites running on free
> software, why do only 1.7% of all computer users have free software on
> their desktops? The answer is simple, the deficiency is :

where do you get the above statistic from? it's a good one but may need
backing up.

> 
> ???not in the software-it is the lack of good free manuals???
> 
> (Free Software Foundation)
> 
> FLOSS Manuals provides high quality manuals about how to use free
> software - to anyone, for free.
> 
> FLOSS Manuals fulfills our mission through our innovative online
> collaborative authoring system. Our community of contributors is lead by
> some of the brightest minds in documentation and free software
> internationally.
> 
> There is nothing like it in terms of content or technology available
> anywhere.

	FM fulfills a vital need for free, high-quality manuals authored by
	experienced users. At the time of writing there is no platform that
	offers this, both in terms of content and the publishing
	technologies we offer.
> 
> * Planned use of prize money:  To hold a Free Documentation Symposium.
> The first of its kind internationally. This event will bring together
> key members of the FLOSS Manuals community with other documentation
> writers to look at techniques and technologies to improve the quality
> and quantity of free documentation.
> 

cheers!

-- 
julian oliver
http://julianoliver.com
http://selectparks.net
messages containing HTML will not be read.