briandominick / codewriting Goto Github PK

There is a lot of research supporting the statement that people skim [your content].

https://uxmyths.com/post/647473628/myth-people-read-on-the-web
https://www.nngroup.com/articles/how-users-read-on-the-web/

Anyone with hotjar (or similar) installed on their site will see this as well. For instance,
http://www.slate.com/articles/technology/technology/2013/06/how_people_read_online_why_you_won_t_finish_this_article.html

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.

One dictionary definition of flat file is a file that does not have internal hierarchy. I don't think that's the what is meant here. Is text-based file what's intended?

I would suggest that flat file be defined or that flat file be changed to text-based. Perhaps:

A flat file is any text-based file. It may be a plain text file, a Python or JavaScript file, or Markdown or even HTML or XML file, including a large number of other file types.

General comment.

Humans are hardwired to connect to story. Back when details were passed along in oral form, it was done in the form of metaphor and story. Putting the user/reader in the position of the hero on his/her/their journey allows the reader to identify their situation and where they are in it. Good documentation will help the reader overcome the hero's obstacle and explain what the resolution was (and any next steps, if there are any).

Figure 3. Semantic structure in Oxygen XML Editor (Source: oxygenxml.com (c) SyncRO Soft SR, republished under Fair Use)

While true that is what the oXygenXML interface can look like I don't think anyone uses that UI very much or for very long. I know I certainly never used it beyond the first couple of days (if that). I frequently switch between Author and Text modes in oXygenXML. It depends on what I'm trying to accomplish. But I never had the semantic tags showing when I was in Author mode. So, I feel it's an unfair comparison, especially since the oXygenXML documentation states that the syntax highlighting is to "reduce the time it takes to internalize the semantics of the structured content." The same could be said about the editor for any tag-based language.

But I don't think the heavy tags-exposed UI is what experienced contributors would use. For casual contributors there are WYSIWYM ways to contribute content (including through a browser without having to install any software) without showing the heavy markup. For casual contributors to tag-based content, it may need to go through a reviewer who is familiar with the required (or preferred) markup -- just like a part of any code review where developers have to adhere to specific coding standards. Perhaps this review and contribution process is not as fast as a lightweight markup language as AsciiDoc or rST, but it's still faster than many alternatives, such as having the developer (or whoever the contributor is) talk at a tech writer. As such, some teams may accept the trade-off.

Well kept, these are also your assets -- they include all the answers SMEs have forgotten or misremembered.

Not just your assets, but the company's assets, and the company should care about its assets. Technical writing and content development is often (always?) seen on the Profit and Loss (P&L) side of the ledger when there is strong reasons it should be listed in the Assets column. Ask any executive if they consider their documentation an asset and you'll likely be met with a quizzical look at best. Ask them what would happen to their business if all of their internal documentation, knowledge bases, notes, scribbles, and so on were lost or destroyed and then ask them if the documentation is an asset. How long would it take to get back up and running, assuming it would be possible at all? Those scribbles are all assets! It does, however, require a broader definition of "documentation" as it moves closer to "intellectual property."

Every executive thinks of their intellectual property as assets, especially assets to be closely guarded. DocOps (or more specifically content strategy) needs to find a way to expose the internally trapped assets through improved processes and automation, while convincing executives that we're not exposing corporate secrets.

No matter what else you learn or forget about the work of technical documentation, remember as
much as you can about writing and writing technically. The rest changes a lot from gig to gig, but the
need for clear, concise, and compelling technical content will remain. Documentation workflows
and methodologies, platforms and toolchains — all the stuff you need proficiency in to call yourself
a DocOps practitioner matters not at all if you cannot write complete, accessible product
explanations and instructions.

I disagree. A writer who does DocOps may need to remember that, especially a lone writer who also has DocOps responsibilities; but someone, say a developer or information architect, for whom writing is not a core job responsibility will not need to heed this recommendation, even if good writing skills are still beneficial for other reasons.

2. Content is managed as discrete components of a whole, instead of merely at the document level

Is it necessary to define what is meant by "document level"? Will documentarians who aren't familiar with topic-based authoring techniques know what "document level" means or "discrete components"? Will it surprise anyone that a document could be one page or hundreds or thousands of pages? But "document" in this sense infers a dead tree format, which doesn't make as much sense when looking at a web page that is only connected to another web page through a hyperlink. Conceptually, they may or may not belong together, but one can be updated without affecting the other. So, where does the "document" begin and where does it end?

For a much longer discussion, see Mark Baker's Every Page is Page One.

I'm trying to build the single page html with a view to adding epub generation. But currently stuck at:

WARN: Problem while copying assets. File exists @ dir_s_mkdir - _build/book-cw/_data
Traceback (most recent call last):
	23: from /home/samuel/.gem/ruby/2.5.0/bin/liquidoc:23:in `<main>'
	22: from /home/samuel/.gem/ruby/2.5.0/bin/liquidoc:23:in `load'
	21: from /home/samuel/.gem/ruby/2.5.0/gems/liquidoc-0.8.1/bin/liquidoc:3:in `<top (required)>'
	20: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/rubygems/core_ext/kernel_require.rb:59:in `require'
	19: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/rubygems/core_ext/kernel_require.rb:59:in `require'
	18: from /home/samuel/.gem/ruby/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:1127:in `<top (required)>'
	17: from /home/samuel/.gem/ruby/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:83:in `config_build'
	16: from /home/samuel/.gem/ruby/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:88:in `iterate_build'
	15: from /home/samuel/.gem/ruby/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:88:in `each'
	14: from /home/samuel/.gem/ruby/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:109:in `block in iterate_build'
	13: from /home/samuel/.gem/ruby/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:745:in `copy_assets'
	12: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:392:in `cp_r'
	11: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1461:in `fu_each_src_dest'
	10: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1477:in `fu_each_src_dest0'
	 9: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1463:in `block in fu_each_src_dest'
	 8: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:393:in `block in cp_r'
	 7: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:415:in `copy_entry'
	 6: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1392:in `wrap_traverse'
	 5: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1392:in `each'
	 4: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1393:in `block in wrap_traverse'
	 3: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1390:in `wrap_traverse'
	 2: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:418:in `block in copy_entry'
	 1: from /home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1265:in `copy'
/home/samuel/.rubies/ruby-2.5.0/lib/ruby/2.5.0/fileutils.rb:1265:in `mkdir': File exists @ dir_s_mkdir - _build/book-cw/_data (Errno::EEXIST)

Deleting the file/dir doesn't help. Any ideas?

The link at the end of the Readme that refers to codewriting.org is misspelled.

Current link -> https://codewriing.org

Like should be -> https://codewriting.org

It's just a typo, but I thought it might matter to anyone else who is as Type-A about docs as I am! :D

I agree that code-like writing is very powerful. No disagreement.

"Only languages and toolchains that offer you inline dynamism — and here I mean DITA as much as
AsciiDoc or RST — actually enhance the power of your writing."

I was doing inline dynamism with unstructured FrameMaker, especially since FrameMaker was scriptable through FrameScript and then later its own, internal scripting language. None of this invalidates what's written, but I want to call attention to the fact that even 1990s-era unstructured FrameMaker could do code-like inline dynamism.

If all you showed me in the last section was screenies or a demo, it's time to get me up and running.

Screenies? I've been in the tech comm field for 20 years and never seen this word. But Urban Dictionary does define the word to mean screen shot. I'm not sure that I would want Urban Dictionary to be my primary source for definitions though. But it's not my book. I'll merely politely suggest that it be changed in favor of a more neutral and understood term (especially by English as second language readers).

I also have a broad definition of what falls under the purview of technical documentation management.
I prefer to be within one hop of every significant technology document the Engineering organization touches, from knowledge base articles to slide decks to drafts of blog posts and white papers.

I would go even further and suggest that bill of materials and build documentation (for hardware products) and code comments should also be considered, among other things that are not considered traditional "documentation." These are closer to "the source," since it actually is the source. We are all about single-sourcing, right? The source doesn't have to be a single, massive repository. In fact, it likely will never be. Instead, pulling together content from numerous silos, where each silo is maintained by its experts using tools they're familiar with.

A crafty DocOps person will query the BOM to build the latest-and-greatest list that users can use to confirm they received everything needed. If the BOM isn't up to date, that's not the tech writer's fault, but if the docs aren't it is. DocOps can help the tech writer by removing the tedious and unnecessary task of duplicating (probably through the error-prone copy-and-paste) someone else's effort. DocOps can improve the user experience, make the company more efficient while at the same time reducing the company's risk. Instead of taking the view of "documentation" DocOps should be pursuing the it's-all-content-and-it-doesn't-matter-where-it-comes-from-or-who-owns-it mentality.

I'm even aware of tools that can take structured files troubleshooting files and automatically create .svg flowcharts out of them. Would you rather read the troubleshooting or would you get through the flowchart faster with it's Yes/No branches? DocOps are the people who integrate tools like that to improve the documentarians life, but also the end user experience.

I think it's worth adding a risk list as well.

Risk:
Open source projects can become stale as contributors move to other projects out of boredom, apathy, or the next cool thing.

For example, the DITA Open Toolkit has just a handful of core contributors, but the number of commercial companies that rely on it are numerous and (appear to) exploit the work of the volunteer core developers without contributing back to the project. Not every project will suffer this circumstance, but some might. The community does not benefit, but only the users of the commercial products.

Just because something is open source does not mean that everyone has access to all of the super cool modifications or updates.

is it expected ?

3. All content can be single-sourced, meaning tech writers and engineers maintain one canonical
   source of truth, no matter how many places that content needs to appear in the generated docs.

This touches on, albeit without saying as much, as Docs as a Service or Content APIs. Content can be subscribed to and pull in based on requests. Consider pulling content into a mobile app, for instance. Too early to reference this sort of pipeline?

Second, “everything in code” means put the docs in the product codebase -- not in a database, not in a separate repository.
This excludes most conventional wiki and web-based CMS platforms, as they depend on relational databases that hide the source behind a tool that is wholly inadequate for source and version control.
We'll discuss integrating your documentation source and platform into the repo and the product itself.
This is addressed in <>.

.DocOps -- General Concept
image::diagram-docops-general.png[]

Is the term "documentation" defined somewhere? I don't recall reading a definition up to this point. I know the definition can be a bit slippery, but if we want to think of docs-as-code, then we not think documentation means lots and lots of words. Most people when they think of "documentation" think long-form content. The diagram-docops-general.png image infers it's more, but the text so far in this book seems to always mean long-form content. If that view is maintained, then it's harder for tech writers to get their hands on the UI strings.

UI strings are documentation (or are at least often used in the documentation). UI strings should be maintained in a separate file (if for no other reason than for localization of the UI) that can be pulled into/sourced by the documentation so that when the UI changes the docs are automatically changed to reflect the updates. Why make work for the tech writer (and of course the developer[s] who have to review the tech writers changes?) -- and that's if the developer even remembers to tell the tech writer the UI changed.

My point here is that the term documentation needs a definition, and the definition itself might be a rather large discussion.

As you'll see, I have a liberal view of what constitutes “technical documentation” at a software company -- probably more in tune with what many call “technical communications”.

This file (and others) does take a very software-centric view of documentation, please do keep in mind the hardware, process, academic and legal documentation that also benefit from DocOps. Even in the open source world there are the Raspberry Pi users who also have to create docs about their products.

(A quick scan of your TOC does indicate that you are aware of and have at least considered that DocOps has a role to play in areas other than software documentation. I encourage you to keep that view in mind.)

I might not be the first one reporting this, but when I'm trying to build the book in PDF and HTML by running bundle exec liquidoc -c _configs/build-global.yml, the output is the following:

bundle exec liquidoc -c _configs/build-global.yml
ERROR: Could not validate input file: The config file (/Users/sergey.rodin/codewriting/_configs/build-global.yml) was not found.
bundler: failed to load command: liquidoc (/Users/sergey.rodin/.rbenv/versions/2.5.0/bin/liquidoc)
RuntimeError: InvalidInput
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:144:in `validate_file_input'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:71:in `config_build'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:1127:in `<top (required)>'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/bin/liquidoc:3:in `require'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/bin/liquidoc:3:in `<top (required)>'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/bin/liquidoc:23:in `load'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/bin/liquidoc:23:in `<top (required)>'

Then, since the _configs directory doesn't exist in the project, I instead point the command to the existing _config directory, like this: bundle exec liquidoc -c _config/build-global.yml. The output I'm getting is this:

INFO: Copied assets to _build.
INFO: File built: _build/pages/resume.adoc
INFO: Generating PDF. This can take some time...
INFO: Rendered file _build/assets/files/brian-dominick-resume.pdf.
INFO: File built: _build/assets/includes/item-lists.adoc
INFO: File built: _build/publish/assets/includes/item-lists.adoc
INFO: File built: _build/book-cw/backmatter/bibliography.adoc
INFO: File built: _build/book-cw/backmatter/glossary.adoc
INFO: File built: _build/pages/docops-glossary.adoc
INFO: Copied _data/glossary.yml to _build/book-cw/_data.
INFO: Copied README.adoc to _build.
INFO: Copied LICENSE.md to _build.
WARN: Problem while copying assets. File exists @ dir_s_mkdir - _build/book-cw/_data
bundler: failed to load command: liquidoc (/Users/sergey.rodin/.rbenv/versions/2.5.0/bin/liquidoc)
Errno::EEXIST: File exists @ dir_s_mkdir - _build/book-cw/_data
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1265:in `mkdir'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1265:in `copy'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:418:in `block in copy_entry'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1390:in `wrap_traverse'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1393:in `block in wrap_traverse'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1392:in `each'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1392:in `wrap_traverse'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:415:in `copy_entry'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:393:in `block in cp_r'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1463:in `block in fu_each_src_dest'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1477:in `fu_each_src_dest0'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:1461:in `fu_each_src_dest'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/2.5.0/fileutils.rb:392:in `cp_r'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:745:in `copy_assets'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:109:in `block in iterate_build'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:88:in `each'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:88:in `iterate_build'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:83:in `config_build'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/lib/liquidoc.rb:1127:in `<top (required)>'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/bin/liquidoc:3:in `require'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/lib/ruby/gems/2.5.0/gems/liquidoc-0.8.1/bin/liquidoc:3:in `<top (required)>'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/bin/liquidoc:23:in `load'
  /Users/sergey.rodin/.rbenv/versions/2.5.0/bin/liquidoc:23:in `<top (required)>'

My _build/publish/ folder only contains this: item-lists.adoc.

The bundler: failed to load command: liquidoc (/Users/sergey.rodin/.rbenv/versions/2.5.0/bin/liquidoc) error seen in both outputs is what I think eventually prevents me from successfully building the files, though I still think it's helpful if my issue is posted here. I'll look elsewhere for the ways to fix it, and go read the PDF from Github for now :)

Docs may not close deals very often, but bad docs can frustrate, costing degrees of a potential customer's confidence.

TODO: find the statistics that say that 60-78% of all enterprise software purchasers read the technical documentation before making a purchase. (I believe this stat comes from IBM; there may be other sources.) Tech docs are as much, if not more so, a part of the pre-sales process as the marketing material, because purchasers don't trust the marketing material in the same way they trust the documentation. With the marketing material they know they're being sold something. With the documentation the default position and assumption is: "just the facts, ma'am," which gives the documentation a fair amount of gravitas.

Dynamic content is extremely powerful. In this section about dynamic writing do you want to keep the section generic about the fact that you can use variables (or whatever they might be called in your markup/language/editor of choice) or do you want it to be specific to AsciiDoc? Or do you want to explore even more?

What's being presented in the AsciiDoc example can be accomplished in other markup languages or tools (and even unstructured FrameMaker has conditional text). I think it's fair to present an AsciiDoc solution, but it should be in its own section outside of the generic information about what you call dynamic writing.

This really raises the question of tool bias (which is totally fine for someone to have -- I have mine) and whether you want this book to be about collaborative DocOps in general or DocOps using a very specific (predetermined) toolset. If it's to be general, which I would encourage, then this section would need some reorganization/rewriting or a number of other examples added, which could get unwieldy (and probably never be exhaustive). If you want the book to have a (very strong) preference for AsciiDoc, then the possible audience is limited. (As I mentioned elsewhere, I'm commenting as I go, so I don't know how many AsciiDoc examples are in the book.)

How far down the dynamic rabbit hole do you want to go? You mention building different doc sets for different audiences, but what if a doc set was built for every individual, which is conceivable with docs being built dynamically based on a user login and account information being used to identify who the reader is and what components they have access to? Such dynamic content and systems exist and should be part of the consideration for a Collaborative DocOps book, in my opinion.

"_Tag-based languages like DITA may provide a degree of dynamism _" It most certainly does! :)
"but for reasons we’ll explore more later, they tend to limit collaboration." Maybe, but maybe not. Because of Lightweight DITA (LwDITA) contributors can create content in XML, HTML, or Markdown making it entirely possible to collaborate or receive content from a large group of people using tools they're familiar with.

Perhaps my point (again) is that DocOps can have a number of different toolchains, and the toolchain that is best for one team may not be the best for another, which should be acknowledged, so that readers can discern what may be best for them.

And that should take readers into issues about how content is going to be reused or repurposed. Will it just be used in docs or will it need to serve other needs, such as chatbots, marketing content, and more? The answer to questions like that determine tools, toolchains, and whether a DLML is sufficient or whether a tag-based language with the necessary metadata is a better fit.

4. Besides the obvious PDF and HTML formats, content can be published as e-book formats, JSON
   objects, Unix man pages, even slide decks for presentations — whatever the situation calls for.

reveal.js FTW
For the truly adventurous who want to involve their marketing friends, then a transform that converts to IDML (InDesign Markup Language) allows super fancy layout in tools they're comfortable with...for white papers.

diagram-docops-general.png
venn-docs-knowledge-truth.png
venn-docs-knowledge-truth-proportionate.png

Given that these are vector images, ideally make as an SVG instead of PNG. Should someone decide to translate this document, it would be easier to translate these files, too. Besides, SVG is well supported now.

https://caniuse.com/#search=svg

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.