{"id":4662,"date":"2010-05-13T17:47:44","date_gmt":"2010-05-13T22:47:44","guid":{"rendered":"http:\/\/www.redmonk.com\/cote\/2010\/05\/13\/makeall004\/"},"modified":"2010-05-13T17:47:44","modified_gmt":"2010-05-13T22:47:44","slug":"makeall004","status":"publish","type":"post","link":"https:\/\/redmonk.com\/cote\/2010\/05\/13\/makeall004\/","title":{"rendered":"Beyond Documentation – make all #004"},"content":{"rendered":"

\"201005131707.jpg\"<\/a><\/p>\n

This week, I talk with a co-worker from my BMC days, Anne Gentle<\/a>. She’s recently come out with a book<\/a> that, as I put it in a short review<\/a>, is trying valiantly to evolve the role that technical publications and those who do it.<\/p>\n

Download the episode directly right here<\/a>, subscribe to the feed<\/a> in iTunes or other podcatcher to have episodes downloaded automatically, or just click play below to listen to it right here:<\/p>\n

\n

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.<\/p>\n

Transcript<\/h2>\n

Michael Cot\u00e9:<\/b> 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 \u2018make all\u2019. The podcast about fun and exciting stuff happening in the software development world. This is your host, Michael Cot\u00e9, as always. And I have a new guest with us, with myself. Would you like to introduce yourself?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> And birds.<\/p>\n

Anne Gentle:<\/b> You will hear it, it\u2019s okay.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s right.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah. And that\u2019s 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?<\/p>\n

Anne Gentle:<\/b> Information Development.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s right.<\/p>\n

Anne Gentle:<\/b> A very special term.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s right. And you were one of the documentation people.<\/p>\n

Anne Gentle:<\/b> Yeah.Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Oh, that\u2019s right. Somehow I managed to get that copy.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, which was like $100 saving for me. I think I still have that book somewhere.<\/p>\n

Anne Gentle:<\/b> Right, it\u2019s on your bookshelf.<\/p>\n

Michael Cot\u00e9:<\/b> It’s very handy reference for obscure stuff that most people don\u2019t care about.<\/p>\n

Anne Gentle:<\/b> That\u2019s 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?<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019t know, phenomenon or whatever of sort of like —<\/p>\n

Anne Gentle:<\/b> Internet phenomenon.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s 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?<\/p>\n

Anne Gentle:<\/b> Well, I often think of this as like, what\u2019s the usual user experience around documentation? And quite honestly, a lot of times it\u2019s a PDF, and I think even, like Tim O\u2019Reilly had some survey and programmers love PDF, and that was maybe from three or four years ago, but that\u2019s kind of where it\u2019s kind of stagnated, where it was like a PDF download. You used to get maybe spiral-bound books.<\/p>\n

Michael Cot\u00e9:<\/b> Oh, right, in cardboard boxes.<\/p>\n

Anne Gentle:<\/b> Oh yeah. They call that the Cardboard Box Integration, I remember those days.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s right.<\/p>\n

Anne Gentle:<\/b> And you had to track it with part numbers, and oh my gosh, it was crazy.<\/p>\n

Michael Cot\u00e9:<\/b> Right.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> Right, right.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

So what I am exploring is, what is the next reincarnation on the web with tech docs.<\/p>\n

Michael Cot\u00e9:<\/b> Beyond just putting a PDF up there.<\/p>\n

Anne Gentle:<\/b> Right, just splatting a PDF on a website.<\/p>\n

Michael Cot\u00e9:<\/b> Or an HTML version of a PDF.<\/p>\n

Anne Gentle:<\/b> Yeah, or an HTML that you have still like this horrible three pane, tri-pane with the Table of Contents on one side and —<\/p>\n

Michael Cot\u00e9:<\/b> Right, right, right.<\/p>\n

Anne Gentle:<\/b> You know, it\u2019s like, there has been no reinvention of what it should — what tech docs can be, I guess.<\/p>\n

Michael Cot\u00e9:<\/b> Right.<\/p>\n

Anne Gentle:<\/b> 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\u2019s not like you could build the docs in two weeks like you needed to with Agile iterations.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah.<\/p>\n

Anne Gentle:<\/b> And that\u2019s 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.<\/p>\n

Michael Cot\u00e9:<\/b> They are not the way you publish a document or something.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

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.<\/p>\n

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.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> It was pulling whenever somebody at Second Life would actually — at Linden Lab would actually do the pull.<\/p>\n

Michael Cot\u00e9:<\/b> So it\u2019s sort of like a manual, push the button and publish it into the game.<\/p>\n

Anne Gentle:<\/b> Yeah, yeah, exactly.<\/p>\n

Michael Cot\u00e9:<\/b> Right, right.<\/p>\n

Anne Gentle:<\/b> 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\u2019t know, it probably has some special name that I am blowing, but anyway —<\/p>\n

Michael Cot\u00e9:<\/b> Whatever fine software they have that lets you like experience the Second Life.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

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.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019s say you go to — let\u2019s say, I don\u2019t 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?<\/p>\n

What is it that you go install to get the full tool chain so that you could — let\u2019s say you get hired by some company like, we need you to do some document, here\u2019s like the budget, go by all your tools. So like what do you get?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> What is topic authoring?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> Right, right.<\/p>\n

Anne Gentle:<\/b> 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 —<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Yeah. Or what is a hanging indent? The concept would actually say, a hanging indent is this in this context and —<\/p>\n

Michael Cot\u00e9:<\/b> What\u2019s a color picker or something?<\/p>\n

Anne Gentle:<\/b> 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\u2019s kind of like HTML versus CSS. You can make it look like anything.<\/p>\n

Michael Cot\u00e9:<\/b> So it\u2019s 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.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019s like the number one lesson I try to get through people\u2019s head is like, whatever problem you have, you should go to Google.<\/p>\n

Anne Gentle:<\/b> Go to Google first, yeah.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019t do that, just go to Google and type in, stump something.<\/p>\n

Anne Gentle:<\/b> Right.<\/p>\n

Michael Cot\u00e9:<\/b> It\u2019s interesting, I feel like probably — I mean, yourself and other — myself and nerdy people, like we kind of —<\/p>\n

Anne Gentle:<\/b> Not a civilian.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Right.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> I do wonder about that. I read somewhere that people — most searches are one word searches. So I guess we are just like —<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, or domain names or something like that.<\/p>\n

Anne Gentle:<\/b> Yeah. YouTube. That’s their search.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Oh man!<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Oh my goodness!<\/p>\n

Michael Cot\u00e9:<\/b> 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 —<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

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.<\/p>\n

Michael Cot\u00e9:<\/b> Right, right.<\/p>\n

Anne Gentle:<\/b> 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?<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, like how they structure that.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, you are sort of looking for an explanation of something to know exactly how something works I guess.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

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.<\/p>\n

Michael Cot\u00e9:<\/b> Right, right.<\/p>\n

Anne Gentle:<\/b> 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?<\/p>\n

Michael Cot\u00e9:<\/b> I mean, this community aspect is something you talk about a lot in your book as far as —<\/p>\n

Anne Gentle:<\/b> Yeah.<\/p>\n

Michael Cot\u00e9:<\/b> So looking at traditional documentation, you think of it, even in the best form is a PDF, which is definitely not a —<\/p>\n

Anne Gentle:<\/b> A brick wall that there is no interest in.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

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.<\/p>\n

Anne Gentle:<\/b> Right.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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\u2019t use it that way, don\u2019t try it.But if you have another set of — and so that might just allow comments, but it wouldn\u2019t allow edits, or only five people can edit it, and they are employees of the company<\/p>\n

Michael Cot\u00e9:<\/b> I mean, that’s sort of like — it\u2019s 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\u2019s not part of the support contract or whatever.<\/p>\n

Anne Gentle:<\/b> Right. So you don\u2019t 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<\/p>\n

Michael Cot\u00e9:<\/b> Yeah. Don\u2019t use the microwave in place of a dryer or something like that.<\/p>\n

Anne Gentle:<\/b> No. We can probably come up with fun examples all afternoon, how not to do something dangerous<\/p>\n

Michael Cot\u00e9:<\/b> Yeah. But then that\u2019s kind of like the new thing is to — and I mean, that\u2019s kind of like abstracting it to another degree. That\u2019s 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\u2019s when you get into the whole like, Wikipedia is destroying knowledge sort of area.<\/p>\n

But scope down it\u2019s 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?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

So I think people are starting to understand it like — but again, it\u2019s either like, well, because customer support is really important to us.<\/p>\n

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\u2019s what hours of — especially when you think about like Facebook being invented out of a college dorm room. Well, it\u2019s 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\u2019s when the real learning occurred.<\/p>\n

So I think that\u2019s another really great case study for community-based content that people can interact with each other.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019s beneficial to have like a study group or whatever.<\/p>\n

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\u2019s nice to have peers kind of discuss and help that rather than just have a textbook that you read.<\/p>\n

Anne Gentle:<\/b> Right. Or just, I am the expertise because I said so, I mean that\u2019s the way some software companies might look at it.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Or they might have a little presentation or two.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> At anytime of the day and asynchronous conversations can happen and —<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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\u2019s recently that — as a technical writer, you can employ like a three-part thing, where first you just monitor what\u2019s 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 —<\/p>\n

Michael Cot\u00e9:<\/b> You are not really trying to be or trusted to be a public representative of the company, right?<\/p>\n

Anne Gentle:<\/b> 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\u2019s kind of that like, you either build it or you find a way to helps a community that\u2019s already kind of thriving. So that\u2019s strategic, that choice alone.<\/p>\n

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.<\/p>\n

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.<\/p>\n

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 —<\/p>\n

Michael Cot\u00e9:<\/b> Sort of selecting the tools to use, right?<\/p>\n

Anne Gentle:<\/b> 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 —<\/p>\n

Michael Cot\u00e9:<\/b> I mean, at this point, there is no end of tools to select.<\/p>\n

Anne Gentle:<\/b> Oh, there are so many. Isn’t it awful? Well, it’s good I guess.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

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.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> Right.<\/p>\n

Anne Gentle:<\/b> Yeah.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

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.<\/p>\n

Michael Cot\u00e9:<\/b> Right, just sort of through the traditional web way of using fame, using eyeballs to kind of figure out what —<\/p>\n

Anne Gentle:<\/b> That attention.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

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.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

And the idea that — and this one is really hard to figure out is the idea that somebody searched for something and they didn\u2019t find anything, how do you make sure that they are on your site for the right reasons but also —<\/p>\n

Michael Cot\u00e9:<\/b> Yeah. I mean, I guess tracking search is a good indication of what — I mean literally what people are interested in, right?<\/p>\n

Anne Gentle:<\/b> Yeah, especially internal search.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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\u00e9:<\/b> Yeah. I mean, that would be like internal matrix sort of stuff for yourself and maybe for your boss to harangue you with.<\/p>\n

Anne Gentle:<\/b> Oh, yeah.<\/p>\n

Michael Cot\u00e9:<\/b> 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 —<\/p>\n

Anne Gentle:<\/b> Yeah, how will you respond.<\/p>\n

Michael Cot\u00e9:<\/b> I don\u2019t know how documentation people are typically rated, but I mean, that seems like a nice — the interaction you have.<\/p>\n

Anne Gentle:<\/b> That’s a better rating than pages per day or some of the crap measurement like that.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, or number of misspellings.<\/p>\n

Anne Gentle:<\/b> 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\u2019s 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Yeah, they love that.<\/p>\n

Michael Cot\u00e9:<\/b> To kind of establish faith that it’s worth their time to explain them that.<\/p>\n

Anne Gentle:<\/b> Right. When I was talking to a Google technical writer, he was saying that, that is in their performance review, page views.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah.<\/p>\n

Anne Gentle:<\/b> Yeah.<\/p>\n

Michael Cot\u00e9:<\/b> Right.<\/p>\n

Anne Gentle:<\/b> So wow, that’s testimony.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> I am done with the web, I need to talk to somebody.<\/p>\n

Michael Cot\u00e9:<\/b> You are getting these weird — it’s sort of like \u2013- 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.<\/p>\n

Anne Gentle:<\/b> You got what you paid for.<\/p>\n

Michael Cot\u00e9:<\/b> But that is like the —<\/p>\n

Anne Gentle:<\/b> Yeah.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> I know. Google\u2019s documentation is so interesting, because a lot of it is written only in FAQ format, so every heading is a question.<\/p>\n

Michael Cot\u00e9:<\/b> Exactly.<\/p>\n

Anne Gentle:<\/b> And it drives me batty after a while.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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:<\/b> I think it’s a perfectly good start.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019t work out, because it’s —<\/p>\n

Anne Gentle:<\/b> Doesn\u2019t help you anymore, I know. And it’s 3:00 in the morning and you haven\u2019t slept well for three nights in a row and you —<\/p>\n

Michael Cot\u00e9:<\/b> It just adds to your anxiety.<\/p>\n

Anne Gentle:<\/b> 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\u2019s — a software doc, I think he is in perfectly good place to start.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

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\u2019t find it and so she couldn\u2019t 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\u2019t 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\u2019s a piece of paper in there. And it seems like that would be a great — that\u2019s 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\u2019s what I did.<\/p>\n

Anne Gentle:<\/b> This was fixed.<\/p>\n

Michael Cot\u00e9:<\/b> 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 —<\/p>\n

Anne Gentle:<\/b> Oh yeah! And it\u2019s users helping each other. I mean, there\u2019s a lot of motivations in that, and you want to save someone else\u2019s wife in that pain in the butt scenario.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

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?<\/p>\n

Anne Gentle:<\/b> 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\u2019s good reasons to do both. I mean, it depends on —<\/p>\n

Michael Cot\u00e9:<\/b> So figure out if you want to line up exactly what development, or if you want to be like an iteration behind or whatever.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> Like we are going to upgrade the Java Runtime Environment or something.Anne Gentle:<\/b> No doc really — no user needs that doc, it might be in Release Notes, like, hey, this is upgraded. Great! So I think there\u2019s 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.<\/p>\n

I also think that if you are on an Agile team, where it\u2019s truly like seven, eight people on a bullpen arrangement, anybody should be able to do the doc, and that\u2019s where you want your documentation tool chain to be so simple to use and explain that you shouldn\u2019t have to know like — you shouldn\u2019t even have to know something is, what I would consider simple, like XML documentation or how you use variables to substitute the product name.<\/p>\n

I mean, it\u2019s 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 —<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019s 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.<\/p>\n

Anne Gentle:<\/b> And what\u2019s 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\u2019s interesting is that, they used to have really credy user-generated content, it wasn\u2019t 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\u2019s something that —<\/p>\n

Michael Cot\u00e9:<\/b> Maybe you go to info graphic.<\/p>\n

Anne Gentle:<\/b> Wouldn\u2019t 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.<\/p>\n

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 —<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> 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\u2019s objects and here is some things you can do with them, and make it more like user scenario oriented.<\/p>\n

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\u2019s how we make money I guess.<\/p>\n

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\u00e9:<\/b> 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 —<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019s 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\u2019s true or not or whatnot, but like what — usually in Open Source discussion, it\u2019s very developer-centric and it\u2019s developers talking about stuff, but as like a technical writer who has been in Open Source stuff, like what do you see that — what\u2019s up with that problem? Is that like a big problem or like how do you — what\u2019s your perspective on that?<\/p>\n

Anne Gentle:<\/b> It\u2019s an interesting problem, and I didn\u2019t 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\u2019s at Ubuntu, where they have the nontechnical end user, like this whole group.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah. At least I — I don\u2019t know if they call it that.<\/p>\n

Anne Gentle:<\/b> You are not one of those, but yeah —<\/p>\n

Michael Cot\u00e9:<\/b> But yeah, because I have been —<\/p>\n

Anne Gentle:<\/b> Not identifying it either.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019s one of their audiences.<\/p>\n

Anne Gentle:<\/b> Yeah. So I think some of — so anyway, that\u2019s 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.<\/p>\n

Michael Cot\u00e9:<\/b> So I mean, have you found that — I mean, do you think that when people complain that there\u2019s not enough documentation in Open Source, which one of those two do you think they are talking about mostly?<\/p>\n

Anne Gentle:<\/b> Probably depends on the project, but there\u2019s 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<\/p>\n

Michael Cot\u00e9:<\/b> You want to charge for it to be easy to use essentially\n<\/p>\n

Anne Gentle:<\/b> Yeah, or you want to charge for a better user experience or something like that.<\/p>\n

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\u2019t 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.<\/p>\n

Michael Cot\u00e9:<\/b> Right.<\/p>\n

Anne Gentle:<\/b> 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\u2019s free as in no charge, but it\u2019s also like free as in, do whatever you want with it. I want you to take this. These chapters you can — even though it\u2019s 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.<\/p>\n

Michael Cot\u00e9:<\/b> Alright.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Well, he decided to bring it to FLOSS Manuals and then they rewrote the whole book with all Open Source tools as the examples.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s interesting, they swapped out the implementation to use the program —<\/p>\n

Anne Gentle:<\/b> Exactly! And that\u2019s 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\u2019t have to spend money on the software, that\u2019s a huge step up.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, that sounds like an interesting book on its own.<\/p>\n

Anne Gentle:<\/b> Yeah.<\/p>\n

Michael Cot\u00e9:<\/b> It\u2019s 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.<\/p>\n

Anne Gentle:<\/b> Right. You are not just clicking menus, you understand why it looks good.<\/p>\n

Michael Cot\u00e9:<\/b> Like what the hell is all this masking? That\u2019s what I always want to know.<\/p>\n

Anne Gentle:<\/b> I do too. Layers I get.<\/p>\n

Michael Cot\u00e9:<\/b> All these hues and different color things are always very confusing.<\/p>\n

Anne Gentle:<\/b> Hue and saturation, and oh my God! But yeah, I mean, this was even like, here\u2019s why a triangle looks good next to a square and here\u2019s the spacing in it. I mean, it was that level of design.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> Yeah, my book is Creative Commons.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> I have been blogging about that lately, just because a lot of people have a lot of myths about Wikis and it shouldn\u2019t mean you can steal anything.<\/p>\n

Michael Cot\u00e9:<\/b> Right.<\/p>\n

Anne Gentle:<\/b> And it\u2019s like — then I really — I didn\u2019t 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\u2019t think it\u2019s 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.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah. Well, I mean nowadays it\u2019s usually to protect the owners of the copyright, it may not necessarily be the —<\/p>\n

Anne Gentle:<\/b> That\u2019s true too, right.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Yeah. I think what licensing really means like — and I guess this is just from my experience with FLOSS Manuals, it\u2019s 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?<\/p>\n

Michael Cot\u00e9:<\/b> Well, I mean, like the example they use, it\u2019s a lot of effort to go through and swap out all — it\u2019s actually like you are rewriting the whole thing.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Like Book Sprints are awesome, they are like Code Sprints, but you end up with the book at the end.<\/p>\n

Michael Cot\u00e9:<\/b> It\u2019s a sort of Agile approach to doing documentation.<\/p>\n

Anne Gentle:<\/b> Right, except for the iterations like Crunch.<\/p>\n

Michael Cot\u00e9:<\/b> Right.<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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?<\/p>\n

Anne Gentle:<\/b> Well, how do they — yeah. And we have had people that come to FLOSS and say, I don\u2019t even know where to start.<\/p>\n

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 —<\/p>\n

Michael Cot\u00e9:<\/b> So money always works.<\/p>\n

Anne Gentle:<\/b> Money always works. It\u2019s 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\u2019s still done by just like a gang of volunteers most definitely.<\/p>\n

Michael Cot\u00e9:<\/b> It\u2019s 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?<\/p>\n

Anne Gentle:<\/b> Yeah.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s 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\u2019t need to like spend five pages talking about how to save a document.<\/p>\n

Anne Gentle:<\/b> Right.<\/p>\n

Michael Cot\u00e9:<\/b> 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\u2019t really have to talk to very much anymore, or I don\u2019t 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?<\/p>\n

Anne Gentle:<\/b> 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 —<\/p>\n

Michael Cot\u00e9:<\/b> But kids are supposed to know how to use anything, right?<\/p>\n

Anne Gentle:<\/b> Yeah, they just intuitively just go for it and they are not intimated. Well, I think even in like —<\/p>\n

Michael Cot\u00e9:<\/b> They don\u2019t need documentation, they are used to cell phones. So it just works.<\/p>\n

Anne Gentle:<\/b> They just try it. Well, it\u2019s all exploratory but —<\/p>\n

Michael Cot\u00e9:<\/b> I always love those stories of the kids, and then it is like, and then here are some kids who didn\u2019t understand that people are reading everything they write. There\u2019s a whole different thing of bad computer literacy that the kids have.<\/p>\n

Anne Gentle:<\/b> Well, that\u2019s 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.<\/p>\n

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.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, we don\u2019t have to explain what Windows are anymore.<\/p>\n

Anne Gentle:<\/b> And you don\u2019t 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.<\/p>\n

Michael Cot\u00e9:<\/b> 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.<\/p>\n

Anne Gentle:<\/b> Here\u2019s the gestures that work.<\/p>\n

Michael Cot\u00e9:<\/b> Like how to spin something or something like that.<\/p>\n

Anne Gentle:<\/b> 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 —<\/p>\n

Michael Cot\u00e9:<\/b> Yeah.<\/p>\n

Anne Gentle:<\/b> But I mean, there\u2019s 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\u2019s just so much cruft in doc that you really can\u2019t get there.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, that\u2019s like the first chapter of every technical book, where like they explain the five icons they are using, which always seems —<\/p>\n

Anne Gentle:<\/b> On the web, that\u2019s so useless.<\/p>\n

Michael Cot\u00e9:<\/b> I am not really sure why they have that. Even in the books, it seems like, I don\u2019t need to understand when you use this typeface, it means that. It\u2019s sort of like, you figured out — and usually to the credit of the people who are figuring out, I don\u2019t know, the typographical and layout conventions, like it\u2019s kind of obvious what they are trying to do.<\/p>\n

Anne Gentle:<\/b> Because it\u2019s consistent.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, like this is a sidebar and this little guy is telling you an example of something, you don\u2019t really need to —<\/p>\n

Anne Gentle:<\/b> 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.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah.<\/p>\n

Anne Gentle:<\/b> Oh, there\u2019s a battery icon, I better go look that up.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, exactly. To your point, when you put that on the web, it\u2019s not like you make people read a five-page introduction before they get to that one paragraph text.<\/p>\n

Anne Gentle:<\/b> Man! Some people still do, but yeah.<\/p>\n

Michael Cot\u00e9:<\/b> Well, great! It’s fun talking about what\u2019s going on in the documentation world. So what\u2019s like your CV handles and everything that you have going on?<\/p>\n

Anne Gentle:<\/b> Oh sure. Well, I stick with Anne Gentle on most all social networks, with Anne with an e.<\/p>\n

Michael Cot\u00e9:<\/b> That\u2019s right.<\/p>\n

Anne Gentle:<\/b> So that\u2019s very easy to find. Gentle is —<\/p>\n

Michael Cot\u00e9:<\/b> And you got the JustWriteClick.<\/p>\n

Anne Gentle:<\/b> JustWriteClick is my blog. Gosh! I got like five years worth of content on there now.<\/p>\n

Michael Cot\u00e9:<\/b> So we have mentioned your book many times; what\u2019s the actual title?<\/p>\n

Anne Gentle:<\/b> Oh sure. The title is \u2018Conversation and Community: The Social Web for Documentation\u2019.<\/p>\n

Michael Cot\u00e9:<\/b> There you go.<\/p>\n

Anne Gentle:<\/b> I swear I want to re-title it the Social Web for Documentation.<\/p>\n

Michael Cot\u00e9:<\/b> Use the subtitle, right?<\/p>\n

Anne Gentle:<\/b> Yeah.<\/p>\n

Michael Cot\u00e9:<\/b> Well, that\u2019s great.<\/p>\n

Anne Gentle:<\/b> Thanks Cot\u00e9.<\/p>\n

Michael Cot\u00e9:<\/b> Yeah, it was a good time.<\/p>\n

Anne Gentle:<\/b> Alright.<\/p>\n

Michael Cot\u00e9:<\/b> I will talk to you sometime soon.<\/p>\n

Anne Gentle:<\/b> Alright.<\/p>\n

Michael Cot\u00e9:<\/b> Thanks everyone for listening.<\/p>\n

Disclosure:<\/b> MindTouch, who Anne mentioned a few times, is a RedMonk customer. See the RedMonk client list<\/a> for other clients mentioned.<\/p>\n","protected":false},"excerpt":{"rendered":"

The evolution of technical documentation.<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[45],"tags":[88,310],"class_list":["post-4662","post","type-post","status-publish","format-standard","hentry","category-makeall","tag-anne","tag-gentle"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/posts\/4662","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/comments?post=4662"}],"version-history":[{"count":0,"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/posts\/4662\/revisions"}],"wp:attachment":[{"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/media?parent=4662"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/categories?post=4662"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/redmonk.com\/cote\/wp-json\/wp\/v2\/tags?post=4662"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}