Lean Docs for Lean Projects - Guides

[lief-erickson]

I fantasized that I would someday get to split the old RefGuide into several editions, all drawing from the same source codebase: • an Analyst’s Guide • an Administrator’s Guide • a Developer’s Guide • a Field Guide

These "Guides" take the 20th century view of the world. They're book (or PDF) based, which is not how 21st century documentation is consumed. Content is consumed by Google and robots and distributed to humans. Soon (and it's happening already), documentation must be available to chatbots and voice-driven systems. Not developing documentation capable of delivering to those systems is tantamount to future pain or failure. Continuing to produce documentation in this structure of "guides," especially for software, is a recipe for, well, problems, especially the likes of "I read it somewhere, but I don't remember in which guide. I wish I knew where it was. I'll have to search." Besides, PDFs just are not (out of the gate) as bot-friendly as HTML, and even the HTML should be marked up with schema.org and dublin core elements.

Again, I point you to Mark Baker's Every Page is Page One

There are mountains of content on Wikipedia, but there's no PDF of Wikipedia. It would be silly to even think of that. Content should be thought of as topics -- discrete, single, and linked to others as necessary. The link is the thing that connects them, not some other artificial organizational structure.

[briandominick]

Everywhere I work, users ask for guides that "cut out the noise". I think that is exactly what topic-based authoring is for. I never said I want to constrain my content into guides and never publish in a format you would like. We will likely do much better here if you ask me for explanations rather than assuming I don't have any, or that you just know better. It's really hard to read critique that doesn't seem to offer any benefit of the doubt. I obviously consider myself a forward-thinking person. I probably get a lot wrong, but calling my ideas "20th century" is just rude. Let's please try to keep this respectful. I have been in the field for under 4 years, and I avoided docs most of my damn life because of what I now recognize as backward thinking (in docs). Organization into guides or publishing of PDF options so people don't need Internet to use Enterprise IT guides -- which is most of what I've done -- is NOT the problem. Assuming you understand everybody's requirements without first having the conversation is very much part of the problem.

[lief-erickson]

Users ask for guides because the information architecture of the website is likely poor. Small data sets are easily served by a table of contents, such as this book. But larger data sets need a search capability, and maybe even this book, too, if I want to find a specific phrase or topic faster than scrolling. So, users are not asking for guides because they actually want guides, they're asking for them because, as you said, they want to cut the noise.

The information architecture that works for a small site doesn't work for a large one. After the amount of information crosses a certain threshold some users become frustrated that they can't find what they're looking for. This isn't a DocOps problem per se -- it's tangential and is properly owned by the information architect or content strategist. To suggest that separately content into guides for software isn't likely addressing the root cause.

Another way to "cut the noise" is to stop publishing so many unneeded topics. There have been a number of studies done in tech pubs, information architecture, and content strategy saying that reducing the amount of content on your website improves findability of your important content while improving user satisfaction. Start deleting topics from your website or PDFs and watch engagement improve. (And if those topics really truly are needed, it's likely by the Support staff, and can be archived off in an internal area just for them, but most likely nobody will miss them.)

I've never been involved with documentation for airlines, but I do know that pilots have thousands and thousands of pages of documentation they need to use. I believe those used to be in three-ring binders. I think iPads are now the delivery mechanism of choice for those. It might be worth investigating how that industry has solved that particular issue. Somebody smarter than me has clearly solved it.

Moreover, I'm commenting on this book as if I were given this and asked to provide direction and feedback. I'll try to choose my words more carefully. If you've only been in this field for just four years I am truly impressed. You, sir, have my respect.

Most tech comm professionals actually have never spoken to a single user in their entire career. They don't actually have first hand knowledge of what users need. Notice I said need not want.

If enterprise IT guides have been your focus, do keep in mind that nearly everybody who is going to be consuming IT enterprise documentation has the internet in their pocket. PDFs don't look good on the things in our pocket. Based on my non-scientific study (although I have asked many, many people) of the question, "if you have a question about a piece of software or hardware, how do you find your answer," the response is always first and always "Google." Followed by "YouTube." It's never "I go to the company's website and search the product documentation." It's also never been "I look in the PDFs I have archived on my computer." (As I said, it's unscientific, anecdotal evidence.)

It's this response more than any that leads me to believe that PDF is not the ideal format for most tech pubs documentation. Why make the user search Google, download a PDF, open a PDF, and then search the PDF? (Restaurants that make me do that to look at their menu infuriate me!) Users already have a browser on their device -- have Google send them directly to your topic and have the user open it in their favorite web browser. It's so much easier for the user. (YMMV.)

There are some very creative and forward thinking people in tech pubs, but a fair number who are stuck using legacy tools who don't know anything other than "we've always done it this way so it must be good." And this is often the fault of managers not valuing what tech pubs has to offer or given the creative freedom to innovate. Many are risk-averse.

// TODO lots of google research needed to back up the myriad claims and conjecture.

[briandominick]

Lief, I never said I suggest publishing only in PDF. I don't even understand where you got that notion. It's really mind-boggling. My entire book is about meeting various needs with single-sourcing. There is nothing un-googlable about product docs that have a web presence and a PDF alternative for those who require or prefer it. I love PDF, I know serious professionals who love PDF, get off of it, please. I'm not denying any options you prefer, afaik, so please just stop.

[briandominick]

I do recognize that what you are saying is true. I would never want to make docs that weren't discoverable on Google. It's offensive that you would suggest that's my goal. I really think you should perhaps finish reading the book before you keep slamming it.