This week, I talk with a co-worker from my BMC days, Anne Gentle. She’s recently come out with a book that, as I put it in a short review, is trying valiantly to evolve the role that technical publications and those who do it.
Download the episode directly right here, subscribe to the feed in iTunes or other podcatcher to have episodes downloaded automatically, or just click play below to listen to it right here:
In this discussion, I ask Anne to walk us through the new role she sees tech writers playing – getting more involved in the community aspects and use of their documents, mostly – and how the “book” changes to fit the way users are now interacting with documentation. We also talk about how documentation writing fits into an Agile process and how the open source world could better take advantage of willing technical writers.
Transcript
Michael Coté: Well, hello everybody! Here we are in a not too hot Austin day. And this is — I forget which episode this is, 4 or 5, an episode of ‘make all’. The podcast about fun and exciting stuff happening in the software development world. This is your host, Michael Coté, as always. And I have a new guest with us, with myself. Would you like to introduce yourself?
Anne Gentle: Sure! Yeah, I am Anne Gentle and we are sitting here in a really nice Austin day, not too hot, not too cool, outdoor, so if you hear traffic.
Michael Coté: And birds.
Anne Gentle: You will hear it, it’s okay.
Michael Coté: That’s right.
Anne Gentle: I have been working on technical writing as a technical writer for 15 years right now, but I am starting to look in ways that we can reinvent, now that we have the web, now that we have the web analytics, now that we can do community-based documentation, what is that like, and especially for software and hardware.
Michael Coté: Yeah. And that’s where we met, when we were both back at BMC, and you were — when I was developing software there and you were in the — what did you guys call yourself, Tech Cubs?
Anne Gentle: Information Development.
Michael Coté: That’s right.
Anne Gentle: A very special term.
Michael Coté: That’s right. And you were one of the documentation people.
Anne Gentle: Yeah.Michael Coté: That was interesting in the sense that, it was interesting for development, because we were starting to do Agile stuff for a very big traditional enterprise software, and so there were all sorts of little weird trickle-out effects of that. And then I think you also gave me a copy of the ITIL Version 2.0 service.
Anne Gentle: Oh, that’s right. Somehow I managed to get that copy.
Michael Coté: Yeah, which was like $100 saving for me. I think I still have that book somewhere.
Anne Gentle: Right, it’s on your bookshelf.
Michael Coté: It’s very handy reference for obscure stuff that most people don’t care about.
Anne Gentle: That’s right. Well, yeah, at BMC, we were just starting out with this solutions-based documentation and Agile was part of it, but we still had this extra team that was trying to figure out ways to talk to customers about how things start to work together, and Business Service Management was just starting to be that buzzword term, right?
Michael Coté: Yeah. I mean, do you think that — since we are going to — I mean, I was interested in talking about, you have a book around this and you have been talking with people and you get a blog and a whole little like, I don’t know, phenomenon or whatever of sort of like —
Anne Gentle: Internet phenomenon.
Michael Coté: That’s right. I mean, of trying to evolve like with technical documentation, to use the common parlance. But I mean, first of all, set a baseline and maybe drawing a little bit on BMC and other sort of stuff like, what do you think is like traditional technical publication like, what does that look like?
Anne Gentle: Well, I often think of this as like, what’s the usual user experience around documentation? And quite honestly, a lot of times it’s a PDF, and I think even, like Tim O’Reilly had some survey and programmers love PDF, and that was maybe from three or four years ago, but that’s kind of where it’s kind of stagnated, where it was like a PDF download. You used to get maybe spiral-bound books.
Michael Coté: Oh, right, in cardboard boxes.
Anne Gentle: Oh yeah. They call that the Cardboard Box Integration, I remember those days.
Michael Coté: That’s right.
Anne Gentle: And you had to track it with part numbers, and oh my gosh, it was crazy.
Michael Coté: Right.
Anne Gentle: But I think there is still a lot of documentation just kind of trapped in — PDF output is the main thing that you get out, they still have that online. But now that the web is coming around and people are starting to understand about Content Management, then you can have these documentation sets that get PDF and HTML out, you may do something with XML, that really lets you do more with the content you have, kind of stretch it, I guess.
Michael Coté: Right, right.
Anne Gentle: Where I really want to stretch it is, how can we — as technical writers we have all these content and the web is exploding in content strategies, always trying to be part of that. And the idea of content curation, where you find the best of everything and put it into this collection.
So what I am exploring is, what is the next reincarnation on the web with tech docs.
Michael Coté: Beyond just putting a PDF up there.
Anne Gentle: Right, just splatting a PDF on a website.
Michael Coté: Or an HTML version of a PDF.
Anne Gentle: Yeah, or an HTML that you have still like this horrible three pane, tri-pane with the Table of Contents on one side and —
Michael Coté: Right, right, right.
Anne Gentle: You know, it’s like, there has been no reinvention of what it should — what tech docs can be, I guess.
Michael Coté: Right.
Anne Gentle: And I get really excited about Wikis. I think you were the one who first is like, when we started doing Agile like, why does it take three days to get this PDF through the review process? And it really was this horrible, slow, it’s not like you could build the docs in two weeks like you needed to with Agile iterations.
Michael Coté: Yeah.
Anne Gentle: And that’s when I was starting to research Wikis; who is doing Wiki? And I think where we are still at now is that, Wikis are used a lot for internal planning, internal collaboration at a company, but Wikis are not necessarily the delivery system yet.
Michael Coté: They are not the way you publish a document or something.
Anne Gentle: Right. Although I saw the most interesting case study last week. A couple of guys from Second Life had just rolled out, I mean literally like two weeks ago rolled out a Wiki Implementation.
So the Wiki was more or less our Content Management System. And then they did this kind of extraction process and got all of their user interface help, that was like, when I am hovering over something that I can do a configuration on in world, I get on the help for that. And they just rolled that out.
But the Wiki was the base, except for they had all these like spaces on the Wiki. So like one name space, only five people could actually edit the content, and then another, there was like any community member could collaborate on any strategy or whatever they wanted to document.
Michael Coté: And then with like the in — not in line, but the in gain help like pull from that or something, or was it kind of like a bidirectional sort of thing?
Anne Gentle: It was pulling whenever somebody at Second Life would actually — at Linden Lab would actually do the pull.
Michael Coté: So it’s sort of like a manual, push the button and publish it into the game.
Anne Gentle: Yeah, yeah, exactly.
Michael Coté: Right, right.
Anne Gentle: It was interesting too because of, translation is always kind of a headache. And they support, I want to say, eight different — what is the world thing called like a Viewer, I don’t know, it probably has some special name that I am blowing, but anyway —
Michael Coté: Whatever fine software they have that lets you like experience the Second Life.
Anne Gentle: Yeah. So like eight clients and they had to support maybe three versions back of each, so that starts to get pretty complicated. You have got to doc that for 24 possibilities.
And then they also translated it to maybe only like four languages. They weren’t in the 20s, like some of the big companies are. But even so, they had to like freeze the Wiki, export it to get French, and then that was their client-based help.
Michael Coté: So nowadays, there is like people using Wikis and other stuff for documentation, but like what would you say is like the standard tool chain for doing docs? Like let’s say you go to — let’s say, I don’t know, you go to the Apple Store, assume you want to get a Mac, because why not, right? You get a new Mac and you are like, alright, I have got to install my stuff. Like what do you install?
What is it that you go install to get the full tool chain so that you could — let’s say you get hired by some company like, we need you to do some document, here’s like the budget, go by all your tools. So like what do you get?
Anne Gentle: One of the projects I have been working on lately is with this company called MindTouch that does like collaborative authoring systems. They actually had a survey where they ask people what is the best tech doc. So I have been studying sites like Apple, definitely on the list, Microsoft, and I think I am seeing a shift where the biggest complemented companies are usually doing some kind of topic authoring, probably in XML, so that they can separate format from content.
Michael Coté: What is topic authoring?
Anne Gentle: Oh! Sure! I am using these like insider terms. So topic authoring is not writing in such a linear structure that you have to have a book to read it, start to finish, so that people can enter from any given point.
Michael Coté: Right, right.
Anne Gentle: So it really changes things, because — another interesting thing about topic authoring is, you might always group topics as task, concept, or reference. If you think about it, you can write anything technical with those three kinds of —
Michael Coté: Right. So there might be something like, how to write a presentation in some presentation software versus how to do a hanging indent. Like very specific sort of things, or kind of like narrations of it, and then, here is the full task.
Anne Gentle: Yeah. Or what is a hanging indent? The concept would actually say, a hanging indent is this in this context and —
Michael Coté: What’s a color picker or something?
Anne Gentle: Yeah, yeah, exactly. So with those three types, you can build about any talks that you want. But I think that was kind of the big reinvention was content separate from format, and that’s kind of like HTML versus CSS. You can make it look like anything.
Michael Coté: So it’s sort of like a decomposition of the traditional book or like a manual. Instead of having chapters that are kind of arranged in a linear fashion, like from knowing nothing to being an expert, which kind of seems like what you are doing. I mean, I guess you can still arrange things that way, but you have more of a focus on a whole bunch of small topics in past.
Anne Gentle: Yeah. And realizing that users come to content very differently. Like I still think I kind of catch people off guard if I say things like, well, Google is the new place that people start before they get to your help site. So you might have this lovingly crafted book, but they are just going in and going out. They are just getting what they need and leaving.
Michael Coté: Yeah. Like whenever I, as I like to call them, whenever I talk with civilians, like non-tech people, like I always try to — it’s like the number one lesson I try to get through people’s head is like, whatever problem you have, you should go to Google.
Anne Gentle: Go to Google first, yeah.
Michael Coté: Like I know you have got an HP printer or you have got like a Microsoft product or whatever and you really think you should go look in the Help section or you should do this, don’t do that, just go to Google and type in, stump something.
Anne Gentle: Right.
Michael Coté: It’s interesting, I feel like probably — I mean, yourself and other — myself and nerdy people, like we kind of —
Anne Gentle: Not a civilian.
Michael Coté: Yeah. Well, we have kind of like learned a little skill of reference librarianism or whatever. Like how to come up with the right keywords and way of phrasing things, and then how to narrow down search results to find something.
Anne Gentle: Right.
Michael Coté: Like I think once every one kind of gets that skill, which hopefully more people will get, then it really changes the way you try to interact with information.
Anne Gentle: I do wonder about that. I read somewhere that people — most searches are one word searches. So I guess we are just like —
Michael Coté: Yeah, or domain names or something like that.
Anne Gentle: Yeah. YouTube. That’s their search.
Michael Coté: And then there are also like sort of horror stories where, my mother-in-law, my wife was helping her out with something, and it took her about 30 minutes to realize that she didn’t realize she needed to scroll to see something.
Anne Gentle: Oh man!
Michael Coté: So there was this exclamation of like, hold it! Wait! You are not seeing that, that’s impossible! And then it turns out, there needed to be some scrolling going on.
Anne Gentle: Oh my goodness!
Michael Coté: But anyhow, so like you are saying, you are looking at this company, and it seemed like a lot of praise for Apple and Microsoft, sort of the topic approach to —
Anne Gentle: That’s my analysis. I mean, IBM was one of the — they have this huge Info Center and it’s all done in this XML standard called DITA, Darwin Information Typing Architecture. And so I was just kind of — it is a standard that you can write to, and they use the Concept Task Reference. So I just think that’s the way a lot of content is moving.
But it also opens up so much more avenue for the web. Like I have an iPod, and I have this Nike sensor that you run and it tells you how far you ran and all that. And it’s like not that hard to set up, but if I have to troubleshoot, I go out in Google, I search, and I will hit the Apple site.
Michael Coté: Right, right.
Anne Gentle: So I think that’s the way most technical content is going. Although, it is interesting, because Apple has this huge Reference Library if you have a programming need; I am not a programmer, but I was studying it to see. Well, how are they organizing it? What are some of the entry pages? And then once you get to a reference topic, what’s the outline for it?
Michael Coté: Yeah, like how they structure that.
Anne Gentle: Right, right. And a lot of times it’s just kind of, here is considerations — here is an overview and explanation, here are considerations and here are examples.
Michael Coté: Right. That’s a interesting — I mean, do you think — how much do you think documentation needs, like what the end effect looks or the end document or text looks like? How much do you think it differs for like programmers or technical people versus users of software?
Anne Gentle: Oh, I think it differs a lot. I actually found that when I was studying like Windows Mobile Phone for end-user document versus iPhone documentation. It’s very minimal. It’s very white background and few texts, lots of pictures, few words, even some video explanations and stuff. But I think that lot of reference documentation, you just need text to search through to find what you need.
Michael Coté: Yeah, you are sort of looking for an explanation of something to know exactly how something works I guess.
Anne Gentle: Exactly! And a lot of what I am seeing is like, you can really — and especially when I look towards like community documentation, because you don’t want to just go build a community if there is no reason for it, because it will never thrive, right? So you kind of have to look at the business goals of why you might have one in the first place.
So social support communities are kind of taking off, and Twitter for Support is like huge. But it’s still for a specific business goal. So you kind of have to go, as a technical writer, where do you align in the org? What is your value? I mean, maybe you write something that helps people sell the product.
Michael Coté: Right, right.
Anne Gentle: And that kind of segues into Open Source. When you document Open Source, are you trying to get more people to download it and use it? Are you trying to make the user experience better because there is documentation with it? Are you just trying to help people who might be struggling?
Michael Coté: I mean, this community aspect is something you talk about a lot in your book as far as —
Anne Gentle: Yeah.
Michael Coté: So looking at traditional documentation, you think of it, even in the best form is a PDF, which is definitely not a —
Anne Gentle: A brick wall that there is no interest in.
Michael Coté: Yeah. I mean, it’s sort of like a one-to-one relationship of like the reader and the document, there is not really anything around it.
And I guess it’s sort of intentional or not, probably more unintentional, the side effect of publishing something on the web in a topic based way, where it suddenly becomes a lot easier for more people to kind of huddle around the document or o something with it.
Anne Gentle: Right.
Michael Coté: So I think the effects of community are kind of understood in social media and Open Source to some respect, but like what — I mean, what have you seen — what does it mean to have community involved in documentation, like what does that end up — what are examples of what that ends up looking like?
Anne Gentle: Well, I think it ends up looking a lot like how people will just kind of keep segmenting the documentation until — like you might have a core set of people who can edit certain areas. And one thing that I talk about in my book is the idea of like warranted information versus non-warranted, which means as a company we stand behind everything documented here, legal reasons for — just for not giving the users too many headaches. It’s like, you can’t use it that way, don’t try it.But if you have another set of — and so that might just allow comments, but it wouldn’t allow edits, or only five people can edit it, and they are employees of the company
Michael Coté: I mean, that’s sort of like — it’s important to have the official documentation for various different reasons, like this device isn’t made to operate at 30 below zero, so like it’s not part of the support contract or whatever.
Anne Gentle: Right. So you don’t get sued because somebody has sprayed bug spray in their eyes. It’s like, all kinds of bad things that can happen when the doc is horribly wrong
Michael Coté: Yeah. Don’t use the microwave in place of a dryer or something like that.
Anne Gentle: No. We can probably come up with fun examples all afternoon, how not to do something dangerous
Michael Coté: Yeah. But then that’s kind of like the new thing is to — and I mean, that’s kind of like abstracting it to another degree. That’s a huge thing. It seems like you are trying to do is kind of sort out like, not only the role of someone who is doing documentation, but the documentation itself. And then if you mix in all the users participating in that documentation, like that starts to get kind of like a weird — and that’s when you get into the whole like, Wikipedia is destroying knowledge sort of area.
But scope down it’s more of a, how do you manage — how do you ensure that, that sort of crowd sourcing of stuff is actually beneficial for what you are doing, as far as documentation?
Anne Gentle: I mean, this is still like a really experimental area, but I mean, I had a development manager call me up last week and he is like, I just used TurboTax and went to the Intuit’s community to figure something out and it was the best experience I ever had, and I totally want to provide that to my users.
So I think people are starting to understand it like — but again, it’s either like, well, because customer support is really important to us.
Another great case study is the whole idea behind education and training. Like if it literally takes a mechanical engineer 400 hours to get certified on some software tool, then the tech writers providing the training, they might want to help users help each other. I mean, you get to a point where — that’s what hours of — especially when you think about like Facebook being invented out of a college dorm room. Well, it’s because, the educational experience, lecture-based, you only learn so much, but when you took the book back to your room or you went to a study group and you actually sat down and learned it yourself, that’s when the real learning occurred.
So I think that’s another really great case study for community-based content that people can interact with each other.
Michael Coté: Right. So the point there being, that if you have — if community is like — one sort of aspect of community is you have groups of people discussing some document, then obviously it’s beneficial to have like a study group or whatever.
So you have people who are kind of — I guess you can think of like documentation as a way of studying a piece of software and how to use it, and as an education experience, like you are saying, so it’s nice to have peers kind of discuss and help that rather than just have a textbook that you read.
Anne Gentle: Right. Or just, I am the expertise because I said so, I mean that’s the way some software companies might look at it.
Michael Coté: I mean, that is a new benefit. I mean, usually you would have — in the past you would have user groups, where you would just have face-to-face talking and stuff.
Anne Gentle: Or they might have a little presentation or two.
Michael Coté: Yeah. But you can actually do that online and lot more frequently and in smaller chunks, because you are just doing it through the web or whatever.
Anne Gentle: At anytime of the day and asynchronous conversations can happen and —
Michael Coté: So I mean, how have you and have you seen people like, how do they tool up their documentation strategy to that kind of thing, like what do you do with that?
Anne Gentle: Well, I just gave a talk last week called Strategies for the Social Web for Documentation, which, the title is way too long, but anyway, it’s recently that — as a technical writer, you can employ like a three-part thing, where first you just monitor what’s already happening. Then you kind of do an audit of what communities already exist and try to figure out, if you as a technical writer, do you have a role, maybe your role in the company is just to report when you see something on the social web that somebody else needs to be alerted to, because you are not really trained in like conflict resolution, their stuff broke before we —
Michael Coté: You are not really trying to be or trusted to be a public representative of the company, right?
Anne Gentle: Exactly, and a lot of us would want to be. But then, if you find that there is a community that already exists or you think there is like enough kind of demographic data or enough of a business case to build a community, well, it’s kind of that like, you either build it or you find a way to helps a community that’s already kind of thriving. So that’s strategic, that choice alone.
And then third, if you do decide to build a platform, here are the tools, and the tools — I was talking to somebody yesterday who is very much like in the Adobe tool chain, there is Tech Comm Suite. She is also really used to using like MadCap Flare, which is kind of XML-based but it just outputs this tri-pane help. It’s the classic.
But when I told her about — she was starting to research Wikis and she comes to Wikipedia first, and is like, well, it doesn’t work real well for tech docs, it doesn’t have hierarchy, or if it does, it only has two layers. It doesn’t really have access control. Some of the reasons it’s not a good match.
But then I realized that, we are kind of used to this real small help offering toolkit that’s maybe, I want to say less than a dozen choices to make, but then you get into Wikis and it’s like, I think there are 97 on WikiMatrix when I checked. So I think part of the difficulty is —
Michael Coté: Sort of selecting the tools to use, right?
Anne Gentle: Yeah. And the other thing that tech writers have to be aware of is, there are already web Content Management Systems in place at most companies, and so wherever you are already blatting your PDFs, you might start poking around for, what could we do to make it more interactive, more web-based. But that’s the third step, like first of all —
Michael Coté: I mean, at this point, there is no end of tools to select.
Anne Gentle: Oh, there are so many. Isn’t it awful? Well, it’s good I guess.
Michael Coté: Yeah. No, I mean, it is like a typical like sort of plan if there is some new technology that people around cheer about. If you want to try to have this sort of bottom-up way for lack of having a corporate mandate for doing something, you sort of have to — it’s funny, like all emerging technologies end up being this way, whether it’s like Agile or Open Source or whatever, you have to — whoever is interested in seeing — whoever wants to be the champion of it, they have to sort of build up a business case, which is sort of like doing the research to say like, these things are actually happening or they are not happening, in which case I am wasting my time.
And here is like the benefit we would have if we put effort into doing it and here is the tool selection and stuff like that. It can be frustrating for people, because they are like, I didn’t sign up to do this, I just want to use my 12 tools to like publish things.
Anne Gentle: I am really going at FreeMarker. And I think that’s kind of what’s happening in the tech comm world is, I mean Frame is wonderful and it’s great for giant books, and it can do structured authoring actually. It can do topic base, but it was meant for books.
Michael Coté: Right.
Anne Gentle: Yeah.
Michael Coté: And so like — I mean, I guess that’s the big thing — I mean, have you seen a lot of success of someone having like a traditional documentation organization and that kind of like move into this — they allow comments to be added? I mean, it’s like simple things like that, right?
Anne Gentle: I mean, yeah, it’s like the first step. I mean, well, Sun was a great case study, even just two years ago. I mean, the whole Oracle thing, I think, has them kind of trying to figure it out all over again, like our Wiki is right for documentation, but it was a perfect match, because they had Open Source products. So they needed open documentation, perfect match.
So I think in some cases they were actually still writing like some sort of structured authoring system and then exporting to Wiki, but others were editing in Wiki. And the Wiki was the source. It was what was exported to translate into all those languages, and they were actually building community around it. But mostly around, not the tech writers as like these like community managers or leaders, but there were some, like rock star coder, who had the most hits on some video demos that he did. So that was how they built up community.
Michael Coté: Right, just sort of through the traditional web way of using fame, using eyeballs to kind of figure out what —
Anne Gentle: That attention.
Michael Coté: Yeah. I mean, another thing we were talking about before we were recording was, and you mentioned in your book a little bit, is using analytics to sort of like — once you publish something through the web, like actually using, as we used to call it, like web log or analytic monitoring to kind of figure out who is using what and things like that. And like, what are examples of like, when you move beyond to PDF, like how you start to actually monitor the usage of your docs in the field to like better — how do you funnel that back into the feedback?
Anne Gentle: What I am really excited about is this idea, I guess it’s on Jakob Nielsen’s blog or something of Readware. So it’s like how when you are cooking in the kitchen and you pull down your favorite cookbook, it opens to your favorite recipe, just because its got the wear in the spine and everything.
So one of the things I have been thinking about is like, how can you look at a set of documentation and see what’s looked at the most, and we have all these other things you can add on top, like ratings; sometimes they are useful, sometimes they are not. Because popularity doesn’t necessarily indicate — I mean, popularity of an article could mean it’s somehow controversial, I guess.
Michael Coté: Yeah. And there is also the scope problem of like, do you care about what 10,000 people think is useful, or like, do you care about what that one person thinks is useful? So it’s kind of like, depending on what situation — depending on if you are that one person or those 10,000 people, I mean there is all these things to trade off, right?
Anne Gentle: And yet it’s interesting too, because like I was monitoring a help site on Google Analytics for like year-and-a-half, and it just gave you a better sense of like, okay, people only read the stuff Monday through Friday, it’s for their jobs folks. And even just insights like error messages was in the top ten search terms. So that kind of helps you shape, well, we should be writing about those.
And the idea that — and this one is really hard to figure out is the idea that somebody searched for something and they didn’t find anything, how do you make sure that they are on your site for the right reasons but also —
Michael Coté: Yeah. I mean, I guess tracking search is a good indication of what — I mean literally what people are interested in, right?
Anne Gentle: Yeah, especially internal search.
Michael Coté: That’s how Google makes all of its money, right, teeing off of that concept. If you can track that day-to-day and then aggregate it over months or whatever, and then you have those intriguing cases like, here is things — if like 50 people search for something that returns no result, then obviously there is some documentation lack, right?
Anne Gentle: There is a gap. The other one I was thinking about too is like a responsiveness report, where like requests for documentation, how quickly are they filled and how soon does something move from draft to final.Michael Coté: Yeah. I mean, that would be like internal matrix sort of stuff for yourself and maybe for your boss to harangue you with.
Anne Gentle: Oh, yeah.
Michael Coté: I mean, once you sort of wanted it be part of the community of consuming your documents, then of course you want to rate yourself on how can you make them and how fast do you satisfy —
Anne Gentle: Yeah, how will you respond.
Michael Coté: I don’t know how documentation people are typically rated, but I mean, that seems like a nice — the interaction you have.
Anne Gentle: That’s a better rating than pages per day or some of the crap measurement like that.
Michael Coté: Yeah, or number of misspellings.
Anne Gentle: But I think mostly people really want high accuracy in their content, and so if you can just like make sure that the pages that are commented on are either getting kudos, or if you get a comment that says, this is wrong and here’s why and you can incorporate it back in, that’s the kind of stuff, like community reports or community content reports to really help you with.
Michael Coté: And then I guess — I mean, I would think it would be — especially the more technical the audience, it would be encouraging to kind of show them proof that you actually give a damn and are doing something about that.
Anne Gentle: Yeah, they love that.
Michael Coté: To kind of establish faith that it’s worth their time to explain them that.
Anne Gentle: Right. When I was talking to a Google technical writer, he was saying that, that is in their performance review, page views.
Michael Coté: Yeah.
Anne Gentle: Yeah.
Michael Coté: Right.
Anne Gentle: So wow, that’s testimony.
Michael Coté: The frustration I always have with Google stuff is, sometimes I get at the end of my rope and I just want to like call someone or email someone.
Anne Gentle: I am done with the web, I need to talk to somebody.
Michael Coté: You are getting these weird — it’s sort of like –- that frustration is squared with the fact that almost everything from Google that I use is free, right? So it’s kind of like — like on the one hand I get frustrated because I can’t find the answer to some obscure questions and it’s just the dead end, right? But on the other hand it’s also kind of like, well, I get what I pay for.
Anne Gentle: You got what you paid for.
Michael Coté: But that is like the —
Anne Gentle: Yeah.
Michael Coté: I mean, it’s funny, like with all the online community stuff. At some point there is sort of a lack of just like someone to talk to every now and then. But it would be nice if there was a way to — anyways, it’s my own personal problem.
Anne Gentle: I know. Google’s documentation is so interesting, because a lot of it is written only in FAQ format, so every heading is a question.
Michael Coté: Exactly.
Anne Gentle: And it drives me batty after a while.
Michael Coté: Yeah.
Anne Gentle: I mean, it’s kind of — it’s a good technique for getting stuff — just get stuff out there, just get it out there, and then we will work on the web analytics and see what’s working and throw out what’s wrong.
Michael Coté: Along those lines, I mean I have noticed in the past few years, I guess, like one of the things that seems to dominate search results on any topic is like Yahoo! Answers or other things, where there is like this free form question and answer thing. Like does that format kind of play any role in documentation, like what do people think of that kind of stuff?
Anne Gentle: Yeah, I think it really does, because most — well, especially if you look at a startup environment, it’s usually one person answering all the questions. So if you can turn the questions into questions and answers, that’s enough documentation to start with for almost any software.
Michael Coté: I mean, is that a good medium to kind of start out with, that we are going to have a, for lack of a better phrase, a live FAQ, where people can submit questions and we will be answering things and you can kind of start bootstrapping all your documentation based on that?Anne Gentle: I think it’s a perfectly good start.
Michael Coté: Yeah. I mean, it’s funny, my wife and I recently adopted a kid, and so like we are first time parents. So the kid looks a little wane, like oh, he is dying or something, right? So it’s great like — I am saying this very sarcastically, like if you look up in Yahoo Answers and they answered everything, it’s like, well, either nothing is wrong or you should go to the hospital immediately. Like there is a certain extent that, that question answer stuff doesn’t work out, because it’s —
Anne Gentle: Doesn’t help you anymore, I know. And it’s 3:00 in the morning and you haven’t slept well for three nights in a row and you —
Michael Coté: It just adds to your anxiety.
Anne Gentle: Yeah, you are not thinking straight anyway. I mean, you can line up those parenting books and find a different answer in each one, and then you have just got to trust your gut. I guess it’s — a software doc, I think he is in perfectly good place to start.
Michael Coté: Yeah, and it seems like — my favorite like — my infamous bugbear of documentation is like printers. Like printers are — I mean, I know from friends who work at like HP and stuff that they spend all of their intellectual effort in like the print heads and the important stuff. Like, I think that probably explains why their software is always terrible and their documentation is always terrible as well.
I remember, I was out of town recently and we had this new HP printer, which is otherwise fantastic, and it had a paper jam, like an error message. And my wife, Kim, had spent all this time to figure out how to unjam it and she couldn’t find it and so she couldn’t unjam it. And like the end result of like the chain of like what to do was like, take it to a service center, which is like, once you get to that point, like I don’t really know what that means. Does a service center exist that you actually want to go to, aside from like the Genius Bar or something.And of course like, like I get home and like I immediately just like opened it up and pushed the print head aside and there’s a piece of paper in there. And it seems like that would be a great — that’s like one example of where it would be nice like, if there was a follow-up thing, where like I could go to wherever she looked up the instructions and be like, here’s what I did.
Anne Gentle: This was fixed.
Michael Coté: Yeah, like I just pushed it aside and this is how it got fixed, and like that would — you could see how examples of that would fit really well for all sorts of technical documentation stuff where —
Anne Gentle: Oh yeah! And it’s users helping each other. I mean, there’s a lot of motivations in that, and you want to save someone else’s wife in that pain in the butt scenario.
Michael Coté: So another topic I was interested in you talking about, because — and you mentioned it earlier, it was like the kind of like how you, as a documentation person, how you adopt to like — or how you how fit into like Agile cycles. So like in an Agile cycle, you might have like — you might have releases, where in theory everything is supposed to be usable at the end of an iteration, that might be in two-week chunks or month chunks or whatever. I mean, it seems like traditionally, when you are doing documentation, you are kind of keeping up with what development is doing, but you are given a window at the end of that to kind of catch up and document everything.
So how do you like — what do you do differently or what do you do when you are supposed to in-flight be delivering documentation at the same time as code, or is that a wrong assessment of what you are supposed to be doing?
Anne Gentle: Well, whenever somebody as a writer gets started with Agile doc, like I immediately am like, okay, figure out whether a doc task is on the backlog or if you have a separate docs backlog, and there’s good reasons to do both. I mean, it depends on —
Michael Coté: So figure out if you want to line up exactly what development, or if you want to be like an iteration behind or whatever.
Anne Gentle: Sometimes you have to look at the user stories and are they truly user stories or are they, we are going to flip this bit down in something that the user never sees, so 33:00 come into the documentation.
Michael Coté: Like we are going to upgrade the Java Runtime Environment or something.Anne Gentle: No doc really — no user needs that doc, it might be in Release Notes, like, hey, this is upgraded. Great! So I think there’s awfully good reasons to have a separate doc backlog, which would also let you make sure that your doc tool chain is up to snuff.
I also think that if you are on an Agile team, where it’s truly like seven, eight people on a bullpen arrangement, anybody should be able to do the doc, and that’s where you want your documentation tool chain to be so simple to use and explain that you shouldn’t have to know like — you shouldn’t even have to know something is, what I would consider simple, like XML documentation or how you use variables to substitute the product name.
I mean, it’s stuff like that that is just like, trying to get your QA or your developer people to help you with doc, when a doc is just the Spaghetti code kind of thing anyway, you are not going to have an easy time; the barrier to entry is like —
Michael Coté: I mean, in that role, and I remember, you are writing a little bit about this in your new book, I mean it seems like part of that responsibility that a documentation, like a technical writer takes on, it’s kind of like an editor, essentially, of that process, where you are — in that situation, you were just describing, you are no longer the only person writing documentation and yet you are responsible for the documentation, which kind of speaks to being more of an editor or a shepherd or whatever versus like being the creator of the content.
Anne Gentle: And what’s really interesting to me about that is like, these things like content farms cropping up, like demand media has been taken a lot of hits lately, because they are all about user-generated content. What’s interesting is that, they used to have really credy user-generated content, it wasn’t edited or anything, and then they started adding on enough process that it was like quality checked and all of this — finally, they have like 11 people touching every piece of content that goes through their system. So I think that’s something that —
Michael Coté: Maybe you go to info graphic.
Anne Gentle: Wouldn’t that be — touch, touch, touch, this person, this person. But they ended up getting higher quality stuff and quality stuff that even big newspapers want now.
So I think that with Agile documentation, if you are truly — like most people are switching to Agile because of user experience or to somehow make things come out more in tune with what users want, at the right time, and so if you have documentation, that is what the users want at the right time, anybody can create it, as long as somebody is shepherding it and governing it and —
Michael Coté: So I mean, do you see that kind of — in Agile the idea is, you have these smaller iterations so that you get more feedback to make sure you are doing the right thing, rather than waiting 6, 12, 18 months, and do you see that effect playing out in documentation on Agile teams? Like does it happen, they are like, oh, this documentation is actually not as great as it could be, or like we miss something and so now that we have had this review of this iteration like we can actually fix that and do much better? So does that happen frequently?
Anne Gentle: Or like you use to document like — like you would document how to create an object, how to update an object, how to destroy an object, like you would document all these, but all you really need to document is like, here’s objects and here is some things you can do with them, and make it more like user scenario oriented.
Like one of good example that I was thinking about when I was studying this documentation for nonprofit software. Well, nonprofits, they might be a fund raising nonprofit or they might be a membership nonprofit, and so the different tasks that you would pick for someone who is doing fund raising primarily would be different from tasks that you would pick for mostly managing membership and that’s how we make money I guess.
So anyway, to get back to the Agile and how that connects, you would have a doc set that would still let people work in those scenarios, but it would be just this doc set where you can move things around easilyMichael Coté: Right, right. So you are kind of focusing more on the personas or whatever you want to call that, of people who are using it, instead of having the comprehensive 500 page document that covers all kinds of aspects —
Anne Gentle: That no one reads and you can actually have web analytics to prove that. So that just-in-time doc or documentation that really matters for the stories that you are working on, instead of the whole thing.
Michael Coté: Right. So another interesting area that you have gotten involved in more recently or since — I know BMC was doing — like doing documentation in the Open Source world. It’s like a perpetual open item or complaint in the Open Source world that there is like not enough documentation or whatever. I have really never validated if that’s true or not or whatnot, but like what — usually in Open Source discussion, it’s very developer-centric and it’s developers talking about stuff, but as like a technical writer who has been in Open Source stuff, like what do you see that — what’s up with that problem? Is that like a big problem or like how do you — what’s your perspective on that?
Anne Gentle: It’s an interesting problem, and I didn’t even really get involved with Open Source software until One Laptop per Child was kind of my entry into it. And they were doing Wiki-based documentation, but it was very much more either project-oriented, like helping people organize, or it was information geared towards developers, and we were looking at how do we document it for kids or teachers who want to use it.So it was kind of — partially it was an audience shift, because some of documentation for Open Source is for programmers, programmers writing for programmers. But there is this whole sense that you can — there are other audiences — I think it’s at Ubuntu, where they have the nontechnical end user, like this whole group.
Michael Coté: Yeah. At least I — I don’t know if they call it that.
Anne Gentle: You are not one of those, but yeah —
Michael Coté: But yeah, because I have been —
Anne Gentle: Not identifying it either.
Michael Coté: I mean, they are trying to do desktop Linux to some extent, right, which is just nontechnical people using it. So I would hope that’s one of their audiences.
Anne Gentle: Yeah. So I think some of — so anyway, that’s why documentation for Open Source can be defined many different ways, because it depends on who you are writing for and who you are delivering for.
Michael Coté: So I mean, have you found that — I mean, do you think that when people complain that there’s not enough documentation in Open Source, which one of those two do you think they are talking about mostly?
Anne Gentle: Probably depends on the project, but there’s also a little bit of difficulty with — if part of coding Open Source is that you give away the artifact of the code, but you want to charge for knowledge or support around it, well, documentation is knowledge and support
Michael Coté: You want to charge for it to be easy to use essentially
Anne Gentle: Yeah, or you want to charge for a better user experience or something like that.
But what I have been getting involved with is a group called FLOSS Manuals, and recently this guy, who is an artist, who was using Open Source software to build like these — like huge art installs I guess, and he was teaching workshops about using the software, and he was like really frustrated because he couldn’t find doc for people who wanted to teach it. So he started this with a grant from the Netherlands government, basically to write open doc for open software.
Michael Coté: Right.
Anne Gentle: So it is a shift, because the documentation itself is all GPL, which I think some people kind of freak out a bit about, if they really do want to retain their rights to the content, to charge for the content or whatever, but he is like, hey, it’s free as in no charge, but it’s also like free as in, do whatever you want with it. I want you to take this. These chapters you can — even though it’s kind of still a book paradigm, it outputs to HTML. So like 10000XL laptops shipped with HTML that came out of this FLOSS Manuals’ Wiki system.
Michael Coté: Alright.
Anne Gentle: Yeah. And it got this whole sense of like, you can remix, so if you — I am trying to think of a toolkit. Oh, okay, so this New York Professor, his last name is Mandiberg, and he wrote this design textbook that was the entire Adobe stack, like Adobe Creative Suite to understand certain design principles. So he wrote this textbook. But he got it licensed through like a Creative Commons license, so he could take the content and do what he wanted with it.
Well, he decided to bring it to FLOSS Manuals and then they rewrote the whole book with all Open Source tools as the examples.
Michael Coté: That’s interesting, they swapped out the implementation to use the program —
Anne Gentle: Exactly! And that’s actually really good for college students, because I mean, I know Adobe stuff, but if you can just prove you know the principles and you have portfolio examples, and you didn’t have to spend money on the software, that’s a huge step up.
Michael Coté: Yeah, that sounds like an interesting book on its own.
Anne Gentle: Yeah.
Michael Coté: It’s nice to be grounded in an actual tool, and like to do that kind of study in both directions; to understand the tool, the concepts, and then to understand the abstract context, concepts of that tool.
Anne Gentle: Right. You are not just clicking menus, you understand why it looks good.
Michael Coté: Like what the hell is all this masking? That’s what I always want to know.
Anne Gentle: I do too. Layers I get.
Michael Coté: All these hues and different color things are always very confusing.
Anne Gentle: Hue and saturation, and oh my God! But yeah, I mean, this was even like, here’s why a triangle looks good next to a square and here’s the spacing in it. I mean, it was that level of design.
Michael Coté: Yes. I mean, tangentially related to Open Source, that brings up like, when it comes to licensing, like GPL and Creative Commons and all this stuff, like your book is Creative Commons, right?
Anne Gentle: Yeah, my book is Creative Commons.
Michael Coté: I mean, what do you sort of advice people when they are figuring out that licensing stuff to choose from, because there is a lot of options nowadays?
Anne Gentle: I have been blogging about that lately, just because a lot of people have a lot of myths about Wikis and it shouldn’t mean you can steal anything.
Michael Coté: Right.
Anne Gentle: And it’s like — then I really — I didn’t really — if I really understood Copyright Law in the beginning, the fact that it was created in England in order to protect the creators of something. So I think the idea behind licensing of content is not to — I don’t think it’s so much to protect the creators anymore, but just to make sure — well, it is to protect the creator. If your creator never intended it to be used a certain way, they can stop that with whatever level of license they chose. It could be all rights reserved.
Michael Coté: Yeah. Well, I mean nowadays it’s usually to protect the owners of the copyright, it may not necessarily be the —
Anne Gentle: That’s true too, right.
Michael Coté: Which is a subtle shift, but it has different effects, but I mean there are — like I remember, was it Harlan Ellison or some science fiction writer who had trademarked his name, and I think the effect being, that like, he could legally stop people from using his name for things if he wanted to, or make sure he got paid if his name was used somewhere, which is kind of a clever like individual use of the copyright trademark, intellectual property system and things.
Anne Gentle: Yeah. I think what licensing really means like — and I guess this is just from my experience with FLOSS Manuals, it’s like, even if you have a GPL, can you really do anything else with it like? Are you going to sit there and copy and paste like 500 pages to get it into some other proprietary software system?
Michael Coté: Well, I mean, like the example they use, it’s a lot of effort to go through and swap out all — it’s actually like you are rewriting the whole thing.
Anne Gentle: Well, you know how they did it, they did it with the Book Sprint, and so they already have the chapters and everything outlined, so they are planning ahead.
Like Book Sprints are awesome, they are like Code Sprints, but you end up with the book at the end.
Michael Coté: It’s a sort of Agile approach to doing documentation.
Anne Gentle: Right, except for the iterations like Crunch.
Michael Coté: Right.
Anne Gentle: But that was how they managed to pull it off, they had probably, I want to say 10 or 12 people who knew enough about the Open Source tools to just rewrite it and cited examples.
Michael Coté: So there is this FLOSS Manuals group out there, and like, I mean, what other — so for people who complained about there not being enough documentation in Open Source, like what — like how do they engage with like the technical writer world to kind of get that? How do they help themselves?
Anne Gentle: Well, how do they — yeah. And we have had people that come to FLOSS and say, I don’t even know where to start.
So like a couple of good approaches, one group actually wrote a grant for, I mean less than $10,000 probably to hold a Book Sprint, to fly people in who were the experts of the product. Buy a stack of plane tickets, get them all in the same room, hire a Book Sprint coordinator and go. I thought that was really effective for like CiviCRM and they had like specific ideas about what they wanted in the user manual.Another approach that —
Michael Coté: So money always works.
Anne Gentle: Money always works. It’s funny, Janet Swisher is a writer here in Austin and she went to this first ever Open Source writers conference, and it was up in Canada and Emma Jane Hogbin hosted it. She is a Drupal expert or whatever. There were literally like probably less than 20 people there, and she and I were like, I think I can count on both hands the number of Open Source writers paid to write. So it’s still done by just like a gang of volunteers most definitely.
Michael Coté: It’s interesting. I mean, Open Source has been successful despite that problem, but then on the other hand, it makes you wonder like, how much better it would be if that problem didn’t exist, right?
Anne Gentle: Yeah.
Michael Coté: That’s right. So the last thing, like when we were talking, I was just thinking about this, how much do you think like ongoing — there needs to be a better phrase for this old phrase, but how much do you think ongoing improvement in computer literacy sort of affects the type and the ways of documentation you have to do? And you were kind of implicitly mentioning this here and there, where maybe you don’t need to like spend five pages talking about how to save a document.
Anne Gentle: Right.
Michael Coté: My assumptions here could be completely off like with the example of my mother-in-law and scrolling, for example, but I assume there are some basic tasks that you don’t really have to talk to very much anymore, or I don’t know. How do you sort that out, like how do you figure out how literate your audience is, and then not talk about the basics?
Anne Gentle: Yeah. I mean, that is a hard balance to do. I mean, like for OLPC, it was like, kids who have never seen a computer or a screen, a keyboard —
Michael Coté: But kids are supposed to know how to use anything, right?
Anne Gentle: Yeah, they just intuitively just go for it and they are not intimated. Well, I think even in like —
Michael Coté: They don’t need documentation, they are used to cell phones. So it just works.
Anne Gentle: They just try it. Well, it’s all exploratory but —
Michael Coté: I always love those stories of the kids, and then it is like, and then here are some kids who didn’t understand that people are reading everything they write. There’s a whole different thing of bad computer literacy that the kids have.
Anne Gentle: Well, that’s true too. Well, even in like — I was a grad student in 1995 and even then there were tech writers who were documenting, going from like green screen to a terminal, to Windows based.
One of the complaints of this particular conference was, we are running out of metaphor, Windows are very hard to describe, because metaphor breaks down so quickly. Anyway, so it has changed over the years.
Michael Coté: Yeah, we don’t have to explain what Windows are anymore.
Anne Gentle: And you don’t have to explain closing a window or resizing a window, and a lot of that, I think, is because of like user standards, like as long as everything is consistent, you only have to learn it once and then you get it the next time, as long as it behaves the way you think it should.
Michael Coté: So I guess, for example, if you are documenting an application on that Microsoft Surface thing or some big touch interface, that might be where you have to explain a bunch of basic things.
Anne Gentle: Here’s the gestures that work.
Michael Coté: Like how to spin something or something like that.
Anne Gentle: Yeah. So each interface change, you would probably have to swap out what you think users know, or at least investigate for yourself, what do you —
Michael Coté: Yeah.
Anne Gentle: But I mean, there’s whole swath of documentation you get rid of that are like document conventions. When you see this icon, that means warning. I mean, you know what I mean? I mean, it’s just so much cruft in doc that you really can’t get there.
Michael Coté: Yeah, that’s like the first chapter of every technical book, where like they explain the five icons they are using, which always seems —
Anne Gentle: On the web, that’s so useless.
Michael Coté: I am not really sure why they have that. Even in the books, it seems like, I don’t need to understand when you use this typeface, it means that. It’s sort of like, you figured out — and usually to the credit of the people who are figuring out, I don’t know, the typographical and layout conventions, like it’s kind of obvious what they are trying to do.
Anne Gentle: Because it’s consistent.
Michael Coté: Yeah, like this is a sidebar and this little guy is telling you an example of something, you don’t really need to —
Anne Gentle: And you are not going to like refer to the front of the book if you get confused, I just can’t imagine you would.
Michael Coté: Yeah.
Anne Gentle: Oh, there’s a battery icon, I better go look that up.
Michael Coté: Yeah, exactly. To your point, when you put that on the web, it’s not like you make people read a five-page introduction before they get to that one paragraph text.
Anne Gentle: Man! Some people still do, but yeah.
Michael Coté: Well, great! It’s fun talking about what’s going on in the documentation world. So what’s like your CV handles and everything that you have going on?
Anne Gentle: Oh sure. Well, I stick with Anne Gentle on most all social networks, with Anne with an e.
Michael Coté: That’s right.
Anne Gentle: So that’s very easy to find. Gentle is —
Michael Coté: And you got the JustWriteClick.
Anne Gentle: JustWriteClick is my blog. Gosh! I got like five years worth of content on there now.
Michael Coté: So we have mentioned your book many times; what’s the actual title?
Anne Gentle: Oh sure. The title is ‘Conversation and Community: The Social Web for Documentation’.
Michael Coté: There you go.
Anne Gentle: I swear I want to re-title it the Social Web for Documentation.
Michael Coté: Use the subtitle, right?
Anne Gentle: Yeah.
Michael Coté: Well, that’s great.
Anne Gentle: Thanks Coté.
Michael Coté: Yeah, it was a good time.
Anne Gentle: Alright.
Michael Coté: I will talk to you sometime soon.
Anne Gentle: Alright.
Michael Coté: Thanks everyone for listening.
Disclosure: MindTouch, who Anne mentioned a few times, is a RedMonk customer. See the RedMonk client list for other clients mentioned.
Recent Comments