[FM Discuss] FLOSS Manual for FSlint

John Curwood marketing at lovinglearning.co.nz
Wed Jun 23 04:15:54 PDT 2010 

Ok I have published FSlint. The published manual can be found at:
http://en.flossmanuals.net/FSlint/Introduction

I will add the link from the FM front page in the morning as I am now
very tired. Also I had a couple of strange issues come up:

I had some come up during the process regarding images being "not
readable" in 3 of the chapters, but they were viewable in the published
manual.

However, The chapter "Common interface items" has only one image that
has loaded properly in the published image, all the others just have
their Alt text displayed. (This chapter did not display any errors
during publishing).

As a final note, all the images were displayed properly in the pdf
version of the published manual.

Cheers,

John

On Wed, 2010-06-23 at 10:15 +0200, adam wrote:
> publish it i rekin!
> 
> congrats Chris :))
> 
> 
> adam
> 
> 
> 
> On Wed, 2010-06-23 at 18:11 +1200, John Curwood wrote:
> > Hi Chris,
> > 
> > If you want to see to some of the suggestions that Edward written then
> > let me know once you have finished and I will publish FSlint for you. If
> > you think the manual is ready for publishing with out the additions then
> > let me know and I'll publish it now.  Remember You can always publish
> > what you have now and keep making modifications in the write section and
> > republish once those are finished.
> > 
> > Cheers,
> > 
> > John
> > 
> > On Tue, 2010-06-22 at 22:29 -0400, Edward Cherlin wrote:
> > > Sounds quite promising.
> > > 
> > > On installation: I hope that we can separate installation into package
> > > installation (apt or yum) and configuration. Within the configuration
> > > section, will it be the same on all Linux distros? What are the use
> > > cases? If there aren't too many cases, can you write a procedure for
> > > each, or break the process down into short, common procedures and give
> > > a list for each case? I see FSlint described as a toolkit. Can we
> > > discuss it in terms of individual tools?
> > > 
> > > Do you have a glossary? Are there many terms not familiar to the
> > > novice?  Are some terms used differently in FSlint than elsewhere? Are
> > > terms defined on first use? If you cut and paste those definitions
> > > into a Glossary draft, I can take a look at it and do an editing pass.
> > > 
> > > These questions apply to many other kinds of software.
> > > 
> > > On Sun, Jun 20, 2010 at 10:48, Chris Stackpole <c.stackpole at gmail.com> wrote:
> > > > -----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-----
> > > > _______________________________________________
> > > > 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
>

More information about the Discuss mailing list