'\" t
.\"
.\" You may distribute under the terms of the GNU General Public
.\" License as specified in the file COPYING that comes with the
.\" man-db distribution.
.\"
.\" Sat Nov 27
.\"
.pc
.TH print soapbox "2009-11-28" "1.0" "print"
.SH manuals, man pages
.I according to the mmm, software has two faces, both as important. the code
.I speaks to the machine, and the documentation ``tells its story to the human
.I user.''
The following is also from the fanzine I'm talking about. It's a perhaps
convoluted way of saying that there's a difference between the documents that
keep track of the changes in a piece of software over time, and the documents
that show how a piece of software is used, even if they sometimes get lumped
together. Texinfo is just another documentation format that some people seem
to prefer.
.I in the gnu coding standards, the terms documentation and manual practically
.I mean the same thing. specifically, a manual is a texinfo file, and
.I documentation includes manuals and other things like NEWS files and change
.I logs. in practice, the latter term practically takes the place of the former.
.I regarding unix man pages, gnu suggests that -if adequate- help2man be used to
.I extract a man page from the texinfo file. unlike man pages, gnu manuals should
.I have a ``coherent topic''. as an example, the coding standards note that diff
.I and diff3 are both covered in a single manual, whereas there are two man
.I pages, one for each command.
I think that it's funny that they write implementation does not equal
documentation. I guess that sometimes it's hard to take distance:
.I the people of gnu distinguish between the way in which a program was built,
.I and the way in which it's used. they warn about modelling the documentation
.I after the software:
.B programmers tend to carry over the structure of the program as the
.B structure for its documentation. but this structure is not necessarily
.B good for explaining how to use the program [...] learn to notice when
.B you have unthinkingly structured the documentation like the
.B implementation, stop yourself, and look for better alternatives.
.I the coding standards advise authors to approach users pedagogically, thinking
.I about ``the concepts and questions that a user will have in mind when reading
.I it.'' what's more, the manuals that they write should admit two types of
.I reading: tutorial and reference. it's interesting to note that by tutorial they
.I mean something that a user may want to read straight through.
in this essay, code is the textual aspect of computer technology that may be
loaded up on a text editor and easily changed. i'm consciously avoiding any
discussion on the subject of text editors -- jot down your edits on a piece of
paper and then write them to newfile with echo. what's important to me is that
this be easily accomplished. with enough time and energy, anyone could write
interesting code. the best project would be if my grandmother took the time to
re-write the linux kernel from scratch, and if she kept a record of her
reflections about code. as much as i like pierre menard, this is not feasible.
the processes of code should be manageable without the need of resorting to
too much external technical support. this means that code is relative. what's
code for some will not be code for others.
when it comes down to it, this means that code is text written in one of the
computer languages. code is the active practice of altering half-understood
text files. code are the static characters that silently stare back at you,
and that will not even you give the illusion that you're double-guessing a
machine. it's always evident that someone else was there before you, and that
that person was sloppy. it's just a matter of playing along and locating those
three characters in a text file that will make all the difference on whether
your computer can display postscript or whether it will keep that as a secret
to itself.
my one year experience as a software writer has not been so nice, but really
you should ask someone else with more experience. i've only worked a little as
a freelancer (whatever that means) on some random websites. i've been learning
on the job (whatever that means).
there are probably other ways of saying it, but it's also fine to say that
i've been bored. i don't know why. there have been projects i'm not ashamed
of, but most of the time it hasn't been like that. i wish i could say i was
young i needed the money but i'm not even that young anymore. health insurance
and that type of stuff is a work of fiction. my life is only as long as my
computer's life.
it's depressing to see that some cliches are true. the offices of lab rats
typing looking for the key of the cookie, waiting to be rewarded with a
cookie, and kept awake with coffee. i could have passed out in front of the
computer and no one would have noticed. the feeling that no one knows what
they're doing. the obscure files that you can find inside of some computers.
what i would do is open them for as long as i'd stand it, close my eyes, press
some random keys, close them and try to forget about it. there's determinacy
in software insofar as you can work like this and nothing breaks.
i wish i could live in a mountain and contemplate my mark-up. i wish it was,
but it can't be and it isn't only about the code. if it was only about the
code, i wouldn't need to go out of my room. i don't know what it's about, and i
don't know what i'm talking about. this is the point where i start to have
problems finishing my sentences. likewise, this type of media work is complete
nonsense. it's absurd that i can't find a job, and that i can't hold on to the
jobs that i hate.
after one year of writing software, it's good to go back to the first things i
wrote. maybe there is something of crawling into my bed and pulling up the
covers about it. probably not. i'm just happy. it was great to have imagined
an introductory perl manual where the examples and exercises deal with
generative groff mark-up.