Docs as Code section - PDFs

[lief-erickson]

First, all technical writing should be sourced in markup and compiled to rich output like HTML and PDF, or specialized output such as Unix "man" pages, user interface elements, specialized app content, or even presentation slide decks. This is a pretty broadly accepted technical documentation principle, especially considering pretty much any tool you can think of saves its files in markup, whether the user ever sees that markup or not.

Noooo. No PDF. Please no. Let's not encourage the creation of a dead tree format (even if no trees are being killed upon which to set the type). There are numerous discussions stating both pros and cons of PDF (e.g., Scriptorium, SEJ, and others).

PDFs may have a place, but it's not likely in DocOps (if you want to be talking about content delivered by technical writers or documentarians). PDF gets created because it's "easy." It's also generally very bad and not done well. PDFs create a support issue, too, in that PDFs cannot be push-updated in the same way that HTML, mobile apps, or ebooks can. We want to encourage documentarians to help their support teams by eliminating this conversation:

User: "I have a problem. I'm looking at the documentation and it says, 'blah blah blah' on page 5." Support: "What version of the PDF do you have?" User: "How can I tell...oh, there it says at that bottom of the page. It's v0.8" Support: "Oh, you've got an old version. Take a look in the newest version. It was fixed there."

The user is forced to proactively look for an updated PDF file, something that vast majority won't do. They'll think the file they have is good or good enough. And it may be. Or may not.

Again, PDFs may have a place and can be done properly, but if we should be questioning why someone wants a PDF and perhaps steer them towards better, more appropriate options.

[briandominick]

You're not going to talk me out of PDF. I know too many places that have legitimate requirements for it. The problem you describe is real, but we are miles apart on this issue, portable being a key aspect of PDF. I love PDF, as do plently of other people. I've had users beg for PDFs of docs.

What are the "better, more appropriate options" you reference? If you want to convince me of something, start with the clearly superior alternatives. I'll switch in a heartbeat if you can give me a better portable document format than PDF. It's not websites, mobile apps, or ebooks in all instances, though those are great too. Also easy isn't bad. Easy means it gets done. People who underestimate simplicity scare me, so let's please not slog something because it's not difficult to do.

[lief-erickson]

I might suggest a new section of the book that discusses the pros and cons of PDF vs. (insert other format [probably HTML]). There might also be a separate but connected section that also addresses the complexity and/or maturity of the organization publishing the content and where they are in their tech pubs/DocOps processes.

I'll concede that there are places that do have legitimate reasons to produce PDF (such as any publisher who does actually produce books -- the kind where trees are killed), but I can't think of many good reasons why any software documentation needs to be delivered in PDF nowadays. Even systems not connected to the internet don't need PDFs and can be well served by HTML.

Users may beg for PDF because that's what they're used to asking for not because it's a better format. Again, nobody has ever asked for a PDF of wikipedia!

In short, while PDFs may be sufficient because they're easy to produce so there's something that's semi-decent looking to throw over the wall, they set certain expectations that are difficult to back away from later as the organization matures. Just like it's always difficult to remove a feature from a product after it's been included, no matter how poorly designed or implemented, I suggest that PDF (often) fits that exact same role for documentation.

So, while I may not talk you out of PDF, I do think others should be talked out of it. :)

[briandominick]

You have done a lot of writing about your better options without any specifics. I have spent a lot of time talking with IT professionals who have used my PDFs. It's honestly really gross that you assume I have not. I do not know how to engage with you if you cannot offer me professional respect that I am not just making this stuff up. Your denigration of users I have worked with is such a turn off. Why must you insist that you know better than other people how they prefer to carry out their work? When you make statements like "nobody has ever asked for a PDF of Wikipedia, do you realize how weird it is given that *Wikipedia has built-in PDF output*???? https://en.wikipedia.org/wiki/Help:Download_as_PDF

What am I supposed to do with such hyperbolic claims you wish to make, with the hubris baked into them, only to learn in 4 seconds that you're just dead wrong about something you were arrogantly certain of. How do we proceed if you cannot treat me as if I am a contributor to my own damn book???

[lief-erickson]

I said of Wikipedia not a Wikipedia topic. Clearly, you see a difference in Wikipedia offering to build a PDF of a topic on-the-fly versus someone preordaining what topics should be gathered together for the user, right?

See above for my comment about respect. I'm in awe, actually. Truly impressive what you've accomplished.

I understand this book has been a passion project. You're very close to it, which may make reading certain lines of commentary more difficult than others; I understand that. I experience it myself with work that I've done -- we all do. Moreover, I make no assumption about your users. By that same token, your data sample might be skewed as well. I don't know that one way or the other. My comments are meant to make you question your own assumptions -- just as any editor might. Of course, as you said, it's your book. You're welcome to close, ignore, disregard, or incorporate anything you wish. I have no skin in this -- just trying to assist in what looks to be a great project.

[lief-erickson]

For what it's worth, Wikipedia's Book Creator feature is cool -- but PDF isn't a necessary output; it's optional. This kind of feature is what DocOps should be looking to deliver rather than encouraging pre-built PDFs.

For users who know what topics they want or for those who want to discover topics and add them to their book so that they can cut the noise, this is the feature they're asking for, and may be the ideal feature to add to a large support site. That's where the value-add is! Users (esp., Support, sales engineers, or trainers) can build their own custom set of topics together. They can choose to output to PDF (if it were working, which at the moment it's not) or possibly ODF. Custom docs, with no extra work from tech pubs. Tech pubs just publishes (or updates) topics.

The onus is still on the user to ensure their content is up-to-date, which will happen automatically if they're only viewing the web version of their book. If they have created a PDF, then at least they've already collected their topics and can just reprint to get the latest and greatest.

Of course, this does raise versioning issues (such as, "I need the version of the docs that go with v.3.5 and this site is for 5.0").

In short, docs are hard...but you knew that already.

[briandominick]

On other issues, you have pointed out numerous weaknesses in my material, and I am grateful. When you seem to know something I do not -- which clearly seems to be plenty -- it is trivial for me to recognize and want to absorb. This is obviously not such a case.

I'm totally down with the custom-docs idea. I have discussed this with clients and even tried to start a discussion of it in WtD #general a while back. I have lots of ideas of how to do this. It lends itself well to PDF as an optional output format.

I'm sure my sample is skewed. I'm pretty sure I admit that. I don't know whose isn't, but yeah limited, narrow, all of that. But narrow as it is, it validates PDF output as an option. I don't need your users to want it for me to instruct it. I need some users to want it. And they do. This is not that complicated.

I do appreciate that you have now said two kind things about me and my project, but in my 25 years as a professional writer and editor, I have literally never encountered a "review" of any kind that lacked literally any positive notes up front or among the criticisms. Nor have I ever handled a review that way, other than the smallest and most insignificant. So I really, truly appreciate the contributions, and it's awesome to be engaging on this topic, but I have VAST experience with professional writing settings, and your approach is unique. I realize you going out of your way in the first place is very flattering, and again I sincerely appreciate it, since I don't know how to proactively find people to engage this stuff other than pouncing in WtD :-) But your style is very jarring and unusual, so please bear with me if I'm the one who has to do the adjusting. I don't need direct praise -- I just had no idea that you even liked the book until you made positive comments after 11PM my time.

[lief-erickson]

Fair points, Brian.