[FM Discuss] FLOSS Manual for FSlint

[John Curwood]

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:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> 
> 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
> 
> 
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
> 
> iEYEARECAAYFAkwWudIACgkQA8QwXn4S0qSGtACghYEQrEiKOQ7uBI4ZiduSmlwW
> LGMAn3sYuTrll1mutqp8vbs95adUGGKk
> =D3qv
> -----END PGP SIGNATURE-----
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>