[FM Discuss] FLOSS Manual for FSlint

Sun Jun 20 07:48:39 PDT 2010

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Thanks for the feedback John and Adam!

I have indeed been working on many of John's points. One of them being
to have someone who is a fairly inexperienced user to read through it.
This has been extremely helpful in flushing it out a bit more. We have
finished the first couple of chapters together and with any luck we will
finish the rest either today or tomorrow.

The reason why I was hesitant on adding a install section is that
because it changes as more distros pick it up and add it to their
repo's. The homepage of FSlint keeps an up-to-date how-to on
installation for many different distros. What I did was I added a
paragraph about this in the intro with a link to the homepage where the
reader could find the different methods. I am more then willing to
listen to advice and will create a short install section if that is
preferred.

It is good advice to contact the developer. I will also send them an
email later today. They could provide some really good feedback as well.

Thank you for the help!

Chris Stackpole

adam wrote:
> i took a quick look also at the manual. i didnt know about fslint and so
> many thanks for the very good intro to the software (which just goes to
> show that having a manual in itself is important for promoting a
> software - the first step to getting a software used)
> 
> I think Johns recommendations were good ones and I see you have taken up
> some of those. A section on installing, even just to say "its too much
> to cover here" would be useful as well as a complete list of what
> versions of Linux it runs on
> 
> but other than that it looks good...i will read through the manual more
> thoroughly while i learn about the software :)
> 
> (if the developers of the project dont know you have done this you could
> write to them and see if they would link to it from their project page
> and/or check the content)
> 
> :)
> 
> adam
> 
> 
> On Fri, 2010-06-18 at 06:57 +1200, John Curwood wrote:
>> Hi Chris,
>>
>> Sorry for the delay in replying, the manual is shaping up very nicely,
>> you are doing a great job for your first documentation effort.  I had
>> not herd of FSlint before you asked to create a manual for it, but I
>> think I will have to get a copy.
>>
>> In terms of pointers here are a few Ideas I have:
>>
>> When it comes to writing style, you need a clear idea of the intended
>> audience for your manual (are they complete novices or are they
>> technically adept and just need a few pointers).  It sounds like you are
>> leaning more towards the novice end of the scale so to help get a feel
>> for how it would read get someone you know who falls into that category
>> to read the manual and see how much they understand or get out of it and
>> make a note of their comments for helping to target that audience.
>>
>> They way I would set up each chapter is at the start give a small talk
>> about the tool covered in that chapter and why you would use it before
>> going into the graphical Interface and command line sections.
>>
>> For examples of entries in the command line I would use the 'Formatted'
>> style in the editor to separate it from the standard text.
>>
>> I would probably include a chapter on downloading and installing on
>> different systems (e.g. debian, ubuntu, fetora, etc), especially if the
>> manual is aimed towards the novice user.
>>
>> And Finally if you click on the 'Arange Manual Index' link on the FSlint
>> web home page, you can split the manual up into sections using the 'Add
>> Section' button.  My personal taste would be to split the manual into 3
>> sections:
>> 1- Introduction.  This would include the introduction chapter, the
>> Installation chapter (if you decide to add one) and maybe the common
>> interface items chapter.
>> 2- Using FSlint.  This would include everything from the Duplicates
>> Chapter down to the Redundant White Spaces Chapter.
>> 3- Appendix.  This would include Other Command Line Tools and the
>> Credits Chapter.
>>
>> At the end of the day, most of these comments are more personal
>> taste/style rather than actual criticisms so feel free to use them or
>> not. :-)
>>
>> Keep up the Great Work!
>>
>> cheers,
>>
>> John
>>
>> On Mon, 2010-06-14 at 18:22 -0500, Chris Stackpole wrote:
> 
> Good afternoon,
> 
> I am working on my first FLOSS manual and while it is not yet ready to
> be released I am at the point where I would like some feedback. I do not
> consider myself a writer, however, I was inspired to give writing a
> manual a try after the demonstrations at the Texas Linux Fest.
> 
> FSlint is not a large program and I am not connected to the developers.
> I just use this software a lot and figured I would try my first manual
> on something I knew rather well.
> 
> There is one thing that is bothering me about what I have posted so far.
> I tend to want specific instructions and precise details. So that is
> what I wrote. I wrote what I would like to see reading about this
> software and I posted screenshots that I thought were useful and
> relevant. However, I think I may be too concise in my wording and may
> have over done the screenshots. There are a few chapters that are a tad
> short.
> 
> I would really appreciate any feedback anyone may have for me. I am
> fully aware I have a ways to go and I would love a few pointers in the
> right direction. I do not mind criticism as long as I also know why and
> what I may do to improve the situation.
> 
> Thanks everyone. I appreciate your time and help!
> 
> Chris Stackpole
> 
> 
_______________________________________________
Discuss mailing list
Discuss at lists.flossmanuals.net
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>>>
>>
>> _______________________________________________
>> Discuss mailing list
>> Discuss at lists.flossmanuals.net
>> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net

> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkweKkcACgkQA8QwXn4S0qS/lwCgnTSS7FjSdnSf06R6MwmNKGTp
CicAnA84E+u7UMx49osGH0P2/qHHCxVt
=MI5q
-----END PGP SIGNATURE-----