On Sun, November 12, 2006 9:31 am, Timothy Murphy wrote: > <flame> > Am I alone in thinking that the info program > encourages bad documentation? > > I want to shrink my /home partition > to allow me to set up a clean installation of FC-6 > side-by-side with my FC-5 installation. > This is on a 64-bit machine, > and there were a couple of nasty problems > when I installed FC-5 on this box, > so I thought I'd keep FC-5 there as a fallback. > > I imagine that is what 90% of Linux users > want to use parted for. > But there is nothing I see in the documentation > directed to this end. > I'm sure if I read it all I will find the solution, > but I don't think one should have to go to that much trouble. > > I know it will take a fraction of the time > to use Partition Magic (of which I have a legal copy). > But I'd prefer to use a Linux solution. > > If only people writing documentation > would consider for a moment why people want to use their program. > To my mind, if 90% of users are interested in one application, > then that should be the subject of the documentation, > with other uses relegated to separate chapters or an appendix. > > Also a simple example of usage > (using script or a similar capture program) > is worth a ream of metadata. > It is usually perfectly obvious how to modify an example > to suit one's particular case, while something like > squiggle [options] <io> <xpd> > takes an age to decipher. > </flame> > > > > -- > Timothy Murphy > e-mail (<80k only): tim /at/ birdsnest.maths.tcd.ie > tel: +353-86-2336090, +353-1-2842366 > s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland > An even bigger point for those writing documentation than considering why people are using their program is to acknowledge that those reading the documentation are not as familiar with the program as the developers or documenter. I developed an application and wrote all the documentation for it. While I know my documentation is clear enough for a computer savvy person to use I had to rewrite it at the level of the average user. Many man or info pages and even instructions from others on list like this are very difficult to follow as often the user is deemed to have the same knowledge as the adviser. If I have to ask for information it is a reasonable guess I don't have as much knowledge on the subject as the person giving the advise, yes a bit of an obvious statement but so often those writing the documentation seem to forget. -- Norm
