Big noun pages

I write a lot of technical documentation, and I have a habit of creating what I call big noun pages. You should make 'em, too.

Big noun pages are pages for big nouns: specific, well-known, important things you’d find in a glossary. That’s in contrast to common types of internal documentation, like how-to guides or onboarding documents. Think “Visual Studio” instead of “Setting up Visual Studio 2017 to build our app.”

Be brave, create big noun pages.

What is a big noun page?

A big noun page needs 3 things:

1. A big noun that’s worth defining, that you might find in a glossary. What is a concept or tool that your coworkers need to know?
2. A definition for that term. I just joined the team, what is it?
3. Related links to any relevant articles. What existing documentation is relevant to this big noun?

For example, every Windows dev needs to know about WinUI. So here’s a big noun page for it:

> # WinUI
>
> **WinUI** is the UI framework used by new surfaces in Windows.
> It uses the [XAML](#) language to represent actual UI components,
> similar to its predecessor, [UWP](#).
>
> ## See also
>
> * [Public docs](#)
> * [Debugging WinUI](#)
> * [How to animate WinUI elements with Composition APIs](#)
> * [UWP](#) - an earlier, related UI framework

You can always write more later (these pages tend to grow), but that’s all you need! It may seem sparse, like a stub page on Wikipedia, but that’s the point. Even non-experts can write one.

Where do you put a big noun page?

Folks need to find your big noun pages, though. So put them:

• Somewhere people look. Where does your team typically store things?
• Somewhere linkable. Can you send a link to your new hires?
• Somewhere editable. Can those new hires fix any issues they notice?

Your goal is to build documentation that experts and new hires alike will discover & use.

Folks are much more likely to discover your content somewhere they already look, rather than somewhere new. It’s why I’m not a big fan of glossaries; they can become good hubs, but they can also become duplicative and obsolete (I did like one that automatically underlined terms across a wiki). It’s also why I prefer interlinking articles to creating “category” pages. How many links have you clicked on Wikipedia? How many categories?

Whether your team uses READMEs, Notion, or something in between… go where your team is, as long as people can link to it & keep it up-to-date!

Why create big noun pages?

In my experience, healthy projects “automatically” accumulate documentation. When something gets complicated, someone writes it down. But this tends to yield:

• Tentative, specific pages, written by non-experts as they learn your code ("Running LangChain in Anaconda on ARM")
• Ambitious, all-encompassing pages, written by experts trying to unify everything ("LangChain Tips & Tricks")

Big noun pages fill a critical, unifying role. They make good content easier to find and easier to edit, and they spark virtuous cycles that ensure your docs stay more correct and get more complete.

First, finding.

There are a couple of theories about how programmers search, but I resonate with Brandt, et al 2009, which found:

[Developers] engage in just-in-time learning of new skills and approaches, clarify and extend their existing knowledge, and remind themselves of details deemed not worth remembering.

Devs find this information via information foraging. They “forage” for information based on nearby cues, only pursuing links that have high information scent (links that seem they would yield information, whether or not they do). Big noun pages offer broad information scent: “LangChain” almost certainly appears relevant to any query about LangChain, whereas “Running LangChain in Anaconda on ARM” or “LangChain Tips & Tricks” will only seem relevant to some queries — even if they have useful background info.

This is complemented by a common search tactic called orienteering. When looking for things, folks tend to move in short, purposeful bounds even when they could “teleport” directly to the answer. In Teevan et al 2004, a user ① navigated to the Harvard Math Department website, then ② opened the faculty directory, then ③ located a specific professor to find their office number, instead of just searching for <professor name> office number. Big noun pages aid this type of orienteering: instead of remembering whether your installation guide was called “Install LangChain” or “Download LangChain,” your readers can orienteer to “LangChain” and navigate from there.

And to be clear, people orient their searches around nouns. Barr, Jones, and Regelson 2008 found that “the majority of queries” (~70%) are noun phrases (like free mp3s). And a related study of developers, Hora 2021, found that nouns were by far the most common part of speech in searches, at 63% (verbs were second, at 9%). This same pattern held in another study of non-devs, although the percentage was lower (47%). I suspect that we’ve trained ourselves to search this way because it’s effective & familiar (there’s a reason that Wikipedia articles are nouns). Matching that style in your content is helpful.

Second, editing.

Big noun pages make editing a lot less scary. If I want to explain how to run LangChain on x86, adding a new section to “LangChain” is simple. If the only existing page is "Running LangChain on ARM," do I need to create a completely new page?

People are remarkably willing to write documentation when given the chance, and they are very good at it. One study found that participants completed “67% more” of a task when given access to user-generated annotations in the documentation, and I have fond memories of learning critical details from User-Contributed Notes on the PHP docs. Big noun pages give users a safe space to edit docs.

These two factors mean your documentation tends to stay more correct and more complete:

• Because big noun pages are good orienteering hubs, both experts and novices tend to read your pages.
• Because the pages are low-cost to edit, those experts tend to fix large-scale errors and those novices tend to keep individual parts up-to-date.
• Because big noun pages are good overviews, new writers tend to link out from them and back to them. Thus their “hubness” increases over time.
• Because big noun pages are easy to write, other authors tend to emulate them and write new big noun pages themselves.

Big noun pages make your documentation better.

A real example

As an example, around 2019 I led a small team of volunteers to rewrite the “Telemetry” page on a well-used internal wiki (the prior version was simply a few irrelevant sentences, with virtually no usage). We rebuilt the page: we wrote a general overview of what telemetry was and how it worked, linked out to years of individual pages, then cross-linked each of those pages back to our hub. The result:

• We documented a surprising amount of tribal knowledge that had never been written down — for lack of a good place to put it.
• A partner team took ownership of the page, delighted to add it to their documentation collection.
• Both experts & non-experts kept the page up-to-date, revising the content whenever requirements & tools changed.

Most importantly, though:

• People used the page & found it helpful.

I used the page to orienteer all the time! The biggest problem? Random devs would ask me questions, since I was the last editor.

Conclusion

I love all documentation. It’s time-consuming volunteer work that’s often quite literally thankless. Documenting anything in any way makes the world better, even if you write a narrow, specific, hard-to-find article ("Building the app in Visual Studio with Docker on Windows 10") or a broad overview ("Ben’s Troubleshooting Tips"). If that’s what you want to write, write it.

All I ask — next time you make a new article, consider: would it help to write a big noun page? The answer is almost always yes.

So be brave; create big noun pages.

Thanks to Judy Stolovitz for reviewing this article. ChatGPT assisted with literature searches for this article.