# Modern Technical Writing
Author:: Andrew Etter
## Highlights
> 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, ([Location 28](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=28))
> Writing should be the minimum possible length. ([Location 45](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=45))
> 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. ([Location 52](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=52))
> 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. ([Location 55](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=55))
> 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. ([Location 78](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=78))
> Don't get stuck in the quagmire of trying to help the helpless. ([Location 95](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=95))
> we can roughly divide readers into three groups: users, administrators, and developers. ([Location 97](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=97))
> 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? ([Location 103](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=103))
> In consumer applications, the user is often also the administrator. In business applications, this situation is less common. ([Location 106](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=106))
> At a minimum, product documentation should answer the following questions: What is this product? Why would anyone want it? ([Location 115](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=115))
> 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. ([Location 118](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=118))
> How does this product fit into a broader ecosystem, if at all? Does it have any dependencies? ([Location 120](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=120))
> Where can I acquire this product? If there are multiple distribution packages, which should I choose and why? ([Location 123](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=123))
> How do I install the product? What are the basic configuration options, if any? ([Location 126](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=126))
> What does a simple, start to finish operation look like? ([Location 128](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=128))
> 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. ([Location 128](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=128))
> 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. ([Location 154](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=154))
> 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."). ([Location 157](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=157))
> 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. ([Location 162](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=162))
> 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. ([Location 168](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=168))
> Help Others Write ([Location 179](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=179))
> Strangers will do it for free, and coworkers will do it even if it isn't in their job descriptions. ([Location 183](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=183))
> 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. ([Location 191](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=191))
> Use Lightweight Markup ([Location 207](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=207))
> 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. ([Location 207](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=207))
> 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. ([Location 226](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=226))
> Plenty of lightweight markup languages exist, but only three are really worth discussing: Markdown, reStructuredText, and AsciiDoc. ([Location 240](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=240))
> 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. ([Location 241](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=241))
> 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. ([Location 244](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=244))
> 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. ([Location 255](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=255))
> 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. ([Location 266](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=266))
> choosing Markdown gives you a certain measure of future-proofing. ([Location 269](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=269))
> 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. ([Location 274](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=274))
> For technical writers, the most important reason to use DVCS is that developers prefer them. ([Location 278](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=278))
> 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. ([Location 282](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=282))
> If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. ([Location 284](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=284))
> 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. ([Location 286](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=286))
> 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 ([Location 291](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=291))
> Don't Duplicate ([Location 293](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=293))
> The core idea here is that you should break your writing into bite-sized pieces, often called topics, none of which overlap in content. ([Location 297](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=297))
> you only have to update the documentation in one place. ([Location 298](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=298))
> 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. ([Location 305](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=305))
> Make Static Websites ([Location 309](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=309))
> You can host static websites practically anywhere, including Amazon S3 and GitHub Pages. ([Location 310](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=310))
> Because all it has to do is serve pages (rather than generate them dynamically), the server needs very few hardware resources. ([Location 312](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=312))
> if I had to suggest a few: Sphinx Jekyll Hugo AsciiDoc Middleman Metalsmith MkDocs Hexo ([Location 319](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=319))
> make sure you have a search solution. ([Location 330](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=330))
> GitHub wikis support Markdown, reStructuredText, AsciiDoc, and some other languages that you shouldn't use. ([Location 333](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=333))
> 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. ([Location 339](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=339))
> If you aren't keeping an eye on documentation metrics, you're making a huge mistake. ([Location 348](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=348))
> 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. ([Location 351](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=351))
> 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. ([Location 372](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=372))
> 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. ([Location 376](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=376))
> 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. ([Location 405](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=405))
> generally treat everything as a working draft. ([Location 411](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=411))
> 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. ([Location 487](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=487))
---
Title: Modern Technical Writing
Author: Andrew Etter
Tags: readwise, books
date: 2024-01-30
---
# Modern Technical Writing
Author:: Andrew Etter
## AI-Generated Summary
None
## Highlights
> 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, ([Location 28](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=28))
> Writing should be the minimum possible length. ([Location 45](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=45))
> 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. ([Location 52](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=52))
> 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. ([Location 55](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=55))
> 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. ([Location 78](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=78))
> Don't get stuck in the quagmire of trying to help the helpless. ([Location 95](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=95))
> we can roughly divide readers into three groups: users, administrators, and developers. ([Location 97](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=97))
> 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? ([Location 103](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=103))
> In consumer applications, the user is often also the administrator. In business applications, this situation is less common. ([Location 106](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=106))
> At a minimum, product documentation should answer the following questions: What is this product? Why would anyone want it? ([Location 115](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=115))
> 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. ([Location 118](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=118))
> How does this product fit into a broader ecosystem, if at all? Does it have any dependencies? ([Location 120](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=120))
> Where can I acquire this product? If there are multiple distribution packages, which should I choose and why? ([Location 123](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=123))
> How do I install the product? What are the basic configuration options, if any? ([Location 126](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=126))
> What does a simple, start to finish operation look like? ([Location 128](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=128))
> 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. ([Location 128](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=128))
> 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. ([Location 154](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=154))
> 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."). ([Location 157](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=157))
> 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. ([Location 162](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=162))
> 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. ([Location 168](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=168))
> Help Others Write ([Location 179](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=179))
> Strangers will do it for free, and coworkers will do it even if it isn't in their job descriptions. ([Location 183](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=183))
> 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. ([Location 191](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=191))
> Use Lightweight Markup ([Location 207](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=207))
> 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. ([Location 207](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=207))
> 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. ([Location 226](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=226))
> Plenty of lightweight markup languages exist, but only three are really worth discussing: Markdown, reStructuredText, and AsciiDoc. ([Location 240](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=240))
> 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. ([Location 241](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=241))
> 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. ([Location 244](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=244))
> 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. ([Location 255](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=255))
> 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. ([Location 266](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=266))
> choosing Markdown gives you a certain measure of future-proofing. ([Location 269](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=269))
> 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. ([Location 274](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=274))
> For technical writers, the most important reason to use DVCS is that developers prefer them. ([Location 278](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=278))
> 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. ([Location 282](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=282))
> If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. ([Location 284](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=284))
> 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. ([Location 286](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=286))
> 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 ([Location 291](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=291))
> Don't Duplicate ([Location 293](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=293))
> The core idea here is that you should break your writing into bite-sized pieces, often called topics, none of which overlap in content. ([Location 297](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=297))
> you only have to update the documentation in one place. ([Location 298](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=298))
> 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. ([Location 305](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=305))
> Make Static Websites ([Location 309](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=309))
> You can host static websites practically anywhere, including Amazon S3 and GitHub Pages. ([Location 310](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=310))
> Because all it has to do is serve pages (rather than generate them dynamically), the server needs very few hardware resources. ([Location 312](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=312))
> if I had to suggest a few: Sphinx Jekyll Hugo AsciiDoc Middleman Metalsmith MkDocs Hexo ([Location 319](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=319))
> make sure you have a search solution. ([Location 330](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=330))
> GitHub wikis support Markdown, reStructuredText, AsciiDoc, and some other languages that you shouldn't use. ([Location 333](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=333))
> 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. ([Location 339](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=339))
> If you aren't keeping an eye on documentation metrics, you're making a huge mistake. ([Location 348](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=348))
> 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. ([Location 351](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=351))
> 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. ([Location 372](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=372))
> 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. ([Location 376](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=376))
> 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. ([Location 405](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=405))
> generally treat everything as a working draft. ([Location 411](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=411))
> 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. ([Location 487](https://readwise.io/to_kindle?action=open&asin=B01A2QL9SS&location=487))