hpr-knowledge-base/hpr_transcripts/hpr0957.txt

Episode: 957
Title: HPR0957: Freedom is not Free 3 - Documentation
Source: https://hub.hackerpublicradio.org/ccdn.php?filename=/eps/hpr0957/hpr0957.mp3
Transcribed: 2025-10-08 05:35:36

---

Hello, this is Ahuka. Welcome to the latest in our series called Freedom Is Not Free.
And this is a series in which I've been talking about how we can support free software in
various ways. And one of the things I want to talk about now is I want to talk about
the topic of documentation. Now, this is another area where all of us can be very helpful
to the free software movement. Every project needs documentation and they need documentation
in a variety of ways. So, you know, how are we going to deal with all of this?
Now, I happen to be a project manager in my day job. And documentation is really important.
A lot of the projects that I work on involve software or IT systems, things like that.
And documenting what's going on is always very important. So, I have written documentation.
I have also encountered resistance on creating documentation.
And documentation is one of those things that everyone agrees in the abstract. It's a good thing,
but no one wants to actually take the time to do it. So, I can't tell you how many times
where I'm at work. And I say, you know, we really need to spend some time documenting the system.
And it's, I know, I can't do that. I'm just way too busy. You know, I'm putting out fires everywhere.
I can't take the time to sit down and write documentation.
And so, what usually happens, in fact, this literally happened at work where this fellow who
had who just could never find any time to do documentation suddenly got very ill.
And shortly thereafter died. And so, all of the stuff, all the documentation, he never
got around to writing. Well, you know, people had to figure out how to deal with all of that when
he wasn't around to ask questions. So, you know, it's not a good thing.
Now, in terms of the free software community, you know, if I can't get people to write
documentation when they're on the payroll, you know, it's even harder in the free software world.
At least that's my experience of it. You know, I use, as I've mentioned, I use a KDE
distribution. Kabuntu is my favorite distribution. And, you know, in KDE, you know, you're working
on an application and you go to the help menu and say, yeah, I want to take a look at the help
system. And I can't tell you how many times then I've clicked on that. And I get a message back
that says, no, there is no help here. We don't have any help. You know, that's unfortunate,
but that's really the way it is. Well, if that's the case, you know, how are we going to deal with
that? I really think we need to have better documentation, better help material.
And so, what I want to do is not just encourage people to do it, but give you some ideas about how
to do it, how to think about it, et cetera. So the first thing is that there's actually two kinds
of documentation. All right, there is technical documentation and there's end user documentation.
And knowing which is which is a really good thing. So with technical documentation, what we're,
you know, talking about, this is what the coders would do for each other. All right, and that's,
that's a good thing. All right, if you've coded, if you've written a bunch of code that someone else
is at some point going to have to take over and manage, you know, it's a real good thing if you've
got some kind of documentation, but that might actually even be in the code. It might be a matter of
placing comments in the code that you write that is going to explain how all of that works.
That's not the kind of documentation I'm talking about here that I want to talk about for the
rest of this podcast. I want to focus on the end user documentation. Now, end user documentation
is something that, you know, is for the end user, it is for someone who is not necessarily technical.
I realize, you know, there are the average technical level of the free software users,
probably a little higher, but I don't think that we are interested in saying that free software
is only for the propeller heads out there because that would be a very small audience.
And I'd like to see free software go further and be applied to larger numbers of people.
But to do that, we got to give them a little bit of help.
Now, when you're taking a look at this kind of documentation, one of the big problems you have
is that nobody wants to do it. It's not the sexy part of it. It's not the fun part.
Developers like writing code. They're good at writing code, generally speaking.
And they really don't want to do documentation. A lot of these people are volunteers.
You can't force them to do documentation. Even if they think in the abstract, it'd be nice
if it existed. That doesn't mean they think it's their job to do it. And if we're talking about
end user documentation, I think that's a different skill set. I really don't think that developers
actually are very good at it on average. There may be some exceptions,
but it's not the sort of thing that it strikes me that a developer is naturally going to be good at.
So with end user documentation, if you do have that skill set, if you do have the ability
to explain things to people, in my case, I previous career, I spent some time in the classroom
teaching and got to develop some skills that way. So if you have that kind of skill set,
if you can write something that is clear, transparent, and helpful, this is a great way to make
a contribution. Now, I got to warn you, it can be frustrating because you're dealing with people
who, by and large, either don't understand or just don't want to take the time to get involved.
Now, I'll tell you a story about one. And it doesn't matter what the application was, but
I said, you know, gee, I'd like to help. I've written good documentation before.
And, you know, I think I could help you with this. Let me help you with some documentation. And
they said, oh, that's wonderful. We really need people to do that. So I said, you know, what kind
of stuff do you have now? Do you have any technical documentation or, you know, what do you have?
Well, the answer was, well, we don't have anything. That's what we want you to do.
And so, okay, where's my starting point here? Am I supposed to go off somewhere and
woodshed figuring out how this software works for six months? So if I'm finally in a position
to write something, you know, when I do this at work when I write documentation, what I do is I make
the technical people sit down with me and answer my questions and so forth. So, you know, the bargain
is I won't make you do the writing. I'll do the writing, but you got to talk to me.
And I think you need to do that to do good documentation, okay? Now, the technical documentation
can get you started. You know, if you've got a good feeling for the technology involved, you
know, you can read that, you can figure out a lot. But if you're going to do good end years of
documentation, you need to go way beyond that. And you may be talking to people on the project
that just don't quite understand this. You know, I can't tell. You know, there are so many people
on these projects that have this idea that, well, we put up a wiki. And it's like, okay, that's
going to work for some people, but it's not good end user documentation. You know, and I think
wikis tend to be vastly overused. Oh, we've put up a FAQ. Okay, that's better than nothing,
but that's not really good documentation. So, the end result of all of this is if you're going
to do good documentation, you may have to actually spend some time talking to the people on the
project and explaining to them just what that means. That good documentation is a group effort.
Well, nothing surprising about that. I've been saying all along that everything we do in
free software is a group or community effort. So, how would you go about doing this?
I think you need to change your mindset just a little bit. End users, let's assume we're talking
about people who by and large are not technical. So, what I like to do is I like to do stories.
Now, if you haven't been exposed to this concept, it's something that agile developers
tend to do this pretty well. And you're going to find it in a few other places. But the idea of
stories is you start inventing a person, a user, and saying, you know, what do we know about this
person who we think is going to be using our software? So, for instance, I might say, hey,
this is this software I want my mother to use. All right, let's say it's an email application.
And my mother is getting up in years. She isn't terribly technical, but she's noticed that her
kids are all communicating via email, ensuring pictures via email, and she's feeling kind of left out.
So, we want to get her involved. And then he said, okay, how would I explain this to my mother then?
And the answer is not, I'd say, hey, there's a wiki here, mom, go figure it out. It just doesn't work.
So, I've got this image of this person in my mind, and I'm going to start thinking, okay, what does
she need to, you know, first of all, she's going to have to configure the software. Oh, that's
going to be tough. You know, I'm not going to explain about IMAP and Pop 3 and SMTP to my mother.
You know, maybe I don't need to. You know, maybe this is one of those things where I end up just
doing it myself, but for the standpoint of documentation, how are we going to set this up? Now,
maybe it's going to lead you through that pretty well. You know, when you install the software,
it's going to take you through the configuration part, but you really need to start thinking,
how do I explain that? And then, you know, once you've got it in there and it's configured,
do you want to have folders? How are we going to set that up? So, we have to start explaining
folders. Do you want to have filters that root things to folders, or are we going to start explaining
that? And when you start explaining it, you're going to want to use screenshots. I think with end
user documentation, it is not possible to have too many screenshots. It just makes a bit,
if you can say to people, when you open the application, here's what it looks like.
And, you know, take a screenshot, bring it into a graphics program,
find a way to draw a box around it in, you know, bold red. And so that it's real obvious what
it is you're pointing to, and you say, and this is where you click, and so on. So, you know,
that's the idea of telling a story. Now, maybe another one is this software I'd want to
use it in the classroom. So, the person I want to be writing my documentation for is a teacher.
Now, I have to tell you, there are a lot of K-12 teachers out there that are not very technical.
So, again, you're going to want to write this in such a way that it's going to be intelligible
to people like that. And, again, screenshots, just, you know, be as clear as you can,
take nothing for granted. All right? Another thing, if you're doing the documentation, test it.
All right? So, if you were writing something for Mom, ask Mom to read it and say, Mom, does this
make sense to you? Could you do that? You know, this is a variation on the sort of testing that
people ought to do for user interface. They don't do as often as they should. But, you know,
the people who are real experts on user interface testing say, what you want to do is you want to
put someone in front of the computer, give them a task to do, and then don't offer them any help
at all and see if they can figure it out. That's a good test of whether your user interface actually
makes any sense or not. But, in terms of documentation, I would say, give the documentation to someone
who matches that story. You know, if it's something for a classroom, you know, find a K-12 teacher
and say, hey, would you take a look at this? You know, back when I was developing websites, I was
very concerned about accessibility. So, I asked a friend of mine who was blind to say, would you
check this site out? Can you navigate this site? I mean, that was one of my best tests. If it's
supposed to be accessible to blind people, get a blind person to look at it. So, in terms of
documentation, get some testing, okay? The next thing you'd want to think about, these are the kinds of
things that we often take for granted, but let's be explicit about it. What's the purpose of this
software? Why would I use it? Very often, people are just not clear about this. You know, I remember
some years ago, I was teaching office productivity software at a local college. And one of the things
that I focused on, and we're talking about word processing and spreadsheets and stuff like that,
your standard office productivity software. And I used to say the single most misused
application in all of personal computing is the word processor. And it's misused because nobody
has ever taught you to think about it the way you ought to. No one has ever taught you to use a
word processor the way you should use it to get all of its power. And I could say the same thing
about spreadsheets and, you know, and so forth. So, you know, understanding what is it that you
want to be doing? How should I be thinking about this piece of software? That's a real good question
to have. What are the things that I want to accomplish? Okay? I mean, this becomes part of the
story that you tell, you know, when you're picturing a typical user and figuring out what their
needs are, part of that is to say, well, what are the specific things they want to accomplish?
Right? If I know that mom wants to see pictures of her grandchildren, what do I need to do
to help her to see the pictures of the grandchildren? And the easier I can make that, the better it's
going to be. You know, is this software that I'm going to use on a daily basis or in frequently?
You know, you can develop familiarity with a piece of software if you use it every day.
If you just use it once in a while, it's kind of a different thing. Is this software that I would
use alone or would I use it in combination with other software? It's another really good question
to be thinking about. And if you're going to be using it in combination with other software,
you might want to spend a little time talking about that process. So if my email client is not going
to, well, let's say the email client is displaying the pictures perfectly well, but mom wants to
save them to her hard drive and, you know, maybe put them into a slide show or something. I'd
better start thinking about that. Now, these are just a few of the questions. And we could go and do
people have written books about this. And obviously, we don't have that kind of time.
But I think this is something you can look at. And if you have that right kind of mindset that
you can put yourself in the shoes of someone who doesn't know a lot about computers and say,
what kind of questions would they have? If you can write something that is clear and understandable
and you know how to grab the screenshots and all of that, then this is something you can look at.
And it's an invaluable contribution to free software if you can do that.
Now, one last thing I want to talk about with documentation. And that is the fact that a lot
of the software that we deal with, we really need to be thinking internationally. All right,
I think free software is a very international project. And so there's people all over the world
involved in this. And that means that the documentation may need to go into a whole variety of
different languages. So translating documentation is really important. And I realize, yes, they've
made wonderful strides in computerized translation. And if you take a look at it, it's just not good
enough. There's nothing that compares to having someone who understands the language of the
documentation and the language that they want to put it into. So, you know, every time I read
I was just reading the other day about all these desktops in Extremadura in Spain and all of the
free software that they want to get into is, okay, I'm guessing at some point they're going to
want someone to translate documentation into Spanish so that, you know, school children in Spain
can actually read this and figure out what's going on. And school teachers in Spain can read it and
figure out what's going on. So that's one of the things that I think you could take a look at.
If, again, if you happen to, you know, if you are bilingual or trilingual, whatever, you've got
several different languages going on, take a look at helping with translation. There's
always a need for help there. So, I think that covers everything I wanted to say about documentation.
So, I'm also going to give my pitch at that. As I think I mentioned on the last one, I am also the
publicity director for Ohio Linux Fest and we are looking for speakers. So, if you have anything
you would like to say, some topic you think you could do a presentation on. If you go to the
OhioLinux.org website and I'm going to put this in the show notes so that you can take a look at
what we're looking and we're looking for a wide variety. We want all varieties of skill and
experience level. So, we want stuff for beginners, we want intermediate, we want stuff for advanced,
we want stuff for cis admins, and we want to cover just about anything involving free software,
open hardware. So, we're pretty broad about it and we're looking for speakers. So, if you can
spare a few moments, go check out the website and maybe file a proposal to give a talk.
And so, I'm looking forward to seeing you at OhioLinux Fest if you're in the area, midwest part of
the United States. Otherwise, I'm signing off. This is Ahuka. Thank you.
You have been listening to Hacker Public Radio at Hacker Public Radio. We are a community podcast
network that releases shows every weekday on day through Friday. Today's show, like all our shows,
was contributed by a HBR listener like yourself. If you ever consider recording a podcast,
then visit our website to find out how easy it really is. Hacker Public Radio was founded by
the Digital.Pound and the Infonomicom Computer Club. HBR is funded by the binary revolution
at binref.com. All binref projects are crowd-responsive by linear pages. From shared hosting to
custom private clouds, go to lunarpages.com for all your hosting needs. Unless otherwise stasis,
today's show is released on the creative commons, attribution, share a like,
videos or license.