{"action":"created","issue":{"url":"https://api.github.com/repos/briandominick/codewriting/issues/14","repository_url":"https://api.github.com/repos/briandominick/codewriting","labels_url":"https://api.github.com/repos/briandominick/codewriting/issues/14/labels{/name}","comments_url":"https://api.github.com/repos/briandominick/codewriting/issues/14/comments","events_url":"https://api.github.com/repos/briandominick/codewriting/issues/14/events","html_url":"https://github.com/briandominick/codewriting/issues/14","id":345463990,"node_id":"MDU6SXNzdWUzNDU0NjM5OTA=","number":14,"title":"Docs as Code section - PDFs","user":{"login":"lief-erickson","id":10221562,"node_id":"MDQ6VXNlcjEwMjIxNTYy","avatar_url":"https://avatars0.githubusercontent.com/u/10221562?v=4","gravatar_id":"","url":"https://api.github.com/users/lief-erickson","html_url":"https://github.com/lief-erickson","followers_url":"https://api.github.com/users/lief-erickson/followers","following_url":"https://api.github.com/users/lief-erickson/following{/other_user}","gists_url":"https://api.github.com/users/lief-erickson/gists{/gist_id}","starred_url":"https://api.github.com/users/lief-erickson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lief-erickson/subscriptions","organizations_url":"https://api.github.com/users/lief-erickson/orgs","repos_url":"https://api.github.com/users/lief-erickson/repos","events_url":"https://api.github.com/users/lief-erickson/events{/privacy}","received_events_url":"https://api.github.com/users/lief-erickson/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":2,"created_at":"2018-07-28T17:11:06Z","updated_at":"2018-07-29T04:10:20Z","closed_at":null,"author_association":"NONE","body":"> *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.\r\nThis 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.\r\n\r\nNoooo. 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](https://www.scriptorium.com/2017/03/four-years-later-pdf-is-not-dead/), [SEJ](https://www.searchenginejournal.com/is-pdf-obsolete/254813/), and others). \r\n\r\nPDFs 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:\r\n\r\nUser: \"I have a problem. I'm looking at the documentation and it says, 'blah blah blah' on page 5.\"\r\nSupport: \"What version of the PDF do you have?\"\r\nUser: \"How can I tell...oh, there it says at that bottom of the page. It's v0.8\"\r\nSupport: \"Oh, you've got an old version. Take a look in the newest version. It was fixed there.\"\r\n\r\nThe 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.\r\n\r\nAgain, 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."},"comment":{"url":"https://api.github.com/repos/briandominick/codewriting/issues/comments/408650558","html_url":"https://github.com/briandominick/codewriting/issues/14#issuecomment-408650558","issue_url":"https://api.github.com/repos/briandominick/codewriting/issues/14","id":408650558,"node_id":"MDEyOklzc3VlQ29tbWVudDQwODY1MDU1OA==","user":{"login":"briandominick","id":1264177,"node_id":"MDQ6VXNlcjEyNjQxNzc=","avatar_url":"https://avatars2.githubusercontent.com/u/1264177?v=4","gravatar_id":"","url":"https://api.github.com/users/briandominick","html_url":"https://github.com/briandominick","followers_url":"https://api.github.com/users/briandominick/followers","following_url":"https://api.github.com/users/briandominick/following{/other_user}","gists_url":"https://api.github.com/users/briandominick/gists{/gist_id}","starred_url":"https://api.github.com/users/briandominick/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/briandominick/subscriptions","organizations_url":"https://api.github.com/users/briandominick/orgs","repos_url":"https://api.github.com/users/briandominick/repos","events_url":"https://api.github.com/users/briandominick/events{/privacy}","received_events_url":"https://api.github.com/users/briandominick/received_events","type":"User","site_admin":false},"created_at":"2018-07-29T04:10:20Z","updated_at":"2018-07-29T04:10:20Z","author_association":"OWNER","body":"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\r\n\r\nWhat 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???"}}
{"actor":{"display_login":"briandominick"}}