%% Last Updated: [[2021-02-22]] %% # Modern Technical Writing [Readwise URL](https://readwise.io/bookreview/7893397)---  --- Great documentation makes new hires productive in days instead of weeks, prevents thousands of calls to customer support, is the difference between crippling downtime and rock solid stability, and inspires true, fervent love of development platforms. Technical writing matters, ^148687558 --- Writing should be the minimum possible length. ^148687559 --- Any piece of print documentation should be an absolute minimalist Getting Started guide (complete with requisite legal boilerplate) that directs its recipients to a web page. People are comfortable typing www into a web browser if they need help. ^148687560 --- Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it. Communicating that knowledge is the last step of the process and really shouldn't comprise more than 10% of your time. When people say, "I was writing all day," they don't mean they were intermittently typing for eight straight hours. They mean they spent the entire day engaged in the writing process. And a big part of that process is installing, configuring, and testing software. In other words, learning. ^148687561 --- Technical writers need to be grinders, willing to slowly but surely chip away at the block of ignorance until a beautiful sculpture emerges--or something like that, anyway. ^148687562 --- Don't get stuck in the quagmire of trying to help the helpless. ^148905872 --- we can roughly divide readers into three groups: users, administrators, and developers. ^148905873 --- Administrators install and configure applications. I'm not just talking about server administrators or people with administrator permissions on a computer, but anyone whose concerns are setup and maintenance. How much disk space does the application server fill over time? ^148905874 --- In consumer applications, the user is often also the administrator. In business applications, this situation is less common. ^148905875 --- At a minimum, product documentation should answer the following questions: What is this product? Why would anyone want it? ^148905876 --- The answer to this question shouldn't come from a marketing department. Instead, it should be an honest, buzzword-free appraisal of capabilities and use cases. ^148905877 --- How does this product fit into a broader ecosystem, if at all? Does it have any dependencies? ^148905878 --- Where can I acquire this product? If there are multiple distribution packages, which should I choose and why? ^148905879 --- How do I install the product? What are the basic configuration options, if any? ^148905880 --- This section can be anything from a pictorial walkthrough to a functional code sample--to be clear, not just a couple snippets--but whatever it is, it should take the user from nothing to something. It should be meaty enough to convince readers that they've learned something. ^148905882 --- What does a simple, start to finish operation look like? ^148905881 --- Bias towards including headers, tables, lists, diagrams, and images. These additions make your writing more approachable and simpler to scan than paragraph after paragraph of prose. ^148905883 --- Use inline styles to offset important text. Typically, technical writers use bold for user interface elements ("Click Save."); italics for emphasis ("You must save your work before shutting down."); and monospace for file paths, terminal commands, and code ("Run ./bin/script.sh."). ^148905884 --- One of the most important functions of a technical writer is to record changes to a product. Good change logs convince people to upgrade, inspire confidence in the direction of a product, and help developers take advantage of new features. ^148905885 --- Readers shouldn't have to parse a corny sales pitch about the incredible potential of a new feature in order to learn that push notifications arrived in version 1.8.2. ^148905886 --- Help Others Write ^148905887 --- Strangers will do it for free, and coworkers will do it even if it isn't in their job descriptions. ^148905888 --- Publish Frequently Publishing should not be a special event. It should not be challenging. It shouldn't require anything more than a quick sanity check and a glance at the build log. ^148905889 --- Someone once said, "XML is like violence: if it doesn't solve your problem, you aren't using enough of it." But whoever said this was definitely a) a developer and b) not writing XML by hand. Because writing XML by hand is crazy, in the same way that writing any significant web application in JavaScript is crazy. Application developers should write TypeScript, Dart, CoffeeScript, or practically anything else and then compile to JavaScript. ^148905891 --- Use Lightweight Markup ^148905890 --- one of the tenets of modern technical writing is that everyone is a contributor. Storing content directly in XML-based languages like XHTML, DocBook, and DITA dramatically reduces people's ability to contribute. ^148905892 --- Plenty of lightweight markup languages exist, but only three are really worth discussing: Markdown, reStructuredText, and AsciiDoc. ^148905893 --- Markdown Markdown is simultaneously incredible and infuriating, wonderful and maddening. It's the most widely used lightweight markup language in the world2 and has the cleanest syntax, but it also has a limited set of features and no defined standard. ^148905894 --- These deficiencies have led to a couple dozen "flavors" of Markdown, including MultiMarkdown, Markdown Extra, GitHub Flavored Markdown, and a recent standardization effort called CommonMark. ^148905895 --- reStructuredText reStructuredText (RST) comes from the Python community. Unlike Markdown, it has an actual, standardized implementation. It's also feature-rich, supporting tables3, footnotes, and a wide variety of directives for code and other content blocks. ^148905896 --- AsciiDoc is semantically equivalent to DocBook and is thus a straightforward, obvious improvement to existing DocBook toolchains. This equivalence likely makes it the best choice for creating books, especially ones that require complex formatting. ^148905897 --- choosing Markdown gives you a certain measure of future-proofing. ^148905898 --- LaTeX is a powerful markup language with complex syntax that I purposely didn't mention until now. If you need it, you already know that you need it. If you don't need it (and few outside of academia do), its only purpose is as a stop in your publishing pipeline on the road to a PDF. More on the pipeline later. ^148905899 --- For technical writers, the most important reason to use DVCS is that developers prefer them. ^148905900 --- Atlassian Bitbucket and Stash are both excellent web-based interfaces for managing remote repositories. GitHub and GitHub Enterprise are also great options. While the default user interface, git-gui, is decent, I prefer Atlassian SourceTree and GitHub Desktop. ^148905901 --- If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. ^148905902 --- Documentation and code branches stay in sync. Developers are more likely to contribute if they don't have to clone a separate repository. Of course, this approach also has some cons: If a repository is large (e.g. 2 GB), checking out the entire repository just to access the 40 KB ./docs directory can dramatically slow down documentation builds. Onerous commit hooks and pull request submission policies, designed to keep a code base stable, can make even simple documentation changes a chore. If your product is composed of code from many repositories, a single documentation repository offers simpler builds and a more cohesive writing experience. ^148905903 --- Wherever you store your documentation, place a file named README.md in the root of the repository (or in ./docs). This Markdown file should include: A quick summary of the product being documented Instructions on how to build the documentation locally Instructions on how to contribute ^148905904 --- Don't Duplicate ^148905905 --- The core idea here is that you should break your writing into bite-sized pieces, often called topics, none of which overlap in content. ^148905906 --- you only have to update the documentation in one place. ^148905907 --- Instead of multiple copies, the better approach is to use a feature sometimes called "conditional text." Conditional text lets you selectively include or exclude files (or portions of files) in the final output. AsciiDoc supports conditional text under the name "conditional inclusion macros." reStructuredText supports it through Sphinx with the .. only:: directive. Unfortunately, this feature is not present in Markdown. ^148905908 <!--ID: 1614530440579--> --- Make Static Websites ^148905909 --- You can host static websites practically anywhere, including Amazon S3 and GitHub Pages. ^148905910 --- Because all it has to do is serve pages (rather than generate them dynamically), the server needs very few hardware resources. ^148905911 --- if I had to suggest a few: Sphinx Jekyll Hugo AsciiDoc Middleman Metalsmith MkDocs Hexo ^148905912 --- make sure you have a search solution. ^148905913 --- GitHub wikis support Markdown, reStructuredText, AsciiDoc, and some other languages that you shouldn't use. ^148905914 --- can result in removed or renamed files not being overwritten and persisting on the server. The easy solution is to delete the old site from the server before copying over the new site, but a tool like Rsync can save you the hassle. ^148905915 --- If you aren't keeping an eye on documentation metrics, you're making a huge mistake. ^148905916 --- Metrics rarely serve as an obvious pointer to the correct course of action. Rather, they serve as a valuable check against your thoughts and intuition. ^148905917 --- If you go against my advice and decide to create and distribute PDFs, you might have to create a so-called publishing pipeline. Publishing pipelines are the steps through which lightweight markup files become print-ready documents. All lightweight markup languages build to HTML, but the journey to PDF often requires an extra step--hence the pipeline. ^148905918 --- Pandoc is a marvelous tool for converting between markup formats. It calls itself the Swiss Army knife of markup converters and can convert to and from a huge number of formats. ^148905919 --- Localization, the process of translating documentation to other languages, is a nightmare. If you ever think you need to do it, interface with management and perform a careful cost-benefit analysis, because the process is expensive, time-consuming, error-prone, and tedious. Once you've arrived at what you believe is an accurate estimate for company costs, triple it. Now you have a realistic estimate. ^148905920 --- generally treat everything as a working draft. ^148905921 --- Wikis are fantastic for living documents that grow over time and never need to be marked as belonging to a particular software version. Many software as a service applications fit this description. ^148905922 ---