Examples of good reference docs (from anywhere)?

[EricZinda]

(I don't know if this works, but) @delph-in/erdw , this thread is for collecting good examples of reference documentation, even if it is just one part of something. Please post and describe what we might want to copy/emulate!

[lizcconrad]

This is a little more general than an example, but this is the "documentation paradigm" I mentioned in one of the discussions: https://documentation.divio.com/. It seems very effective and the central point of it is that you must consider the use case/audience you are writing for every time you write a piece of documentation, which I think this group will need to keep in mind since we discussed how certain pages are going to be catered to different audiences.

[EricZinda]

I love that taxonomy! I'm going to start adopting in our discussions to help clarify the focus of the different things we write.

[arademaker]

@lizcconrad, excellent link, and material...

[EricZinda]

I worked on the .Net Framework so I thought I'd see if they have anything we can copy.

The top level overview page clearly directs people towards the different categories: Tutorials (Create your application), HowTos (Develop .NET apps), Explanation (.NET concepts), Reference (API and language reference).

The docs seem to broken into main "sites" that have independent table of contents trees on the left side:

• Conceptual and HowTo
• API Reference
  And lots of other smaller ones like: Azure for mobile developers, Game Development for visual studio, etc.

Explanation Docs

Explanation docs are not versioned, which makes sense since they are conceptual and the high level concepts don't change all that much. I assume they have notes in them about version differences if there were any.

If you look at a conceptual topic like Assemblies in .Net it has some Explanation and some simple Tutorials in in.

Reference Docs

Reference docs are versioned. The entire TOC on the left refers to a particular version and you have to choose which you look at.

They have a good writeup on the Reference docs experience that talks about their "Reference Docs browser" works, how they do versioning, searching, etc.

If you look at a particular reference topic like system.string, you get a ton of information. I'd expect this for one of the most used (and most complicated since it has to do with language) types in the system. At the top is the basic reference stuff, and then farther down are lots of examples and how tos, and some conceptual stuff. You can see the version you are looking at on the left and change it.

Search

Doing a search using the text box on the upper right corner searches across everything as far as I can tell. If you do a search for "system.string" (which would be like searching for something like _the_q, I guess), you get hits across all types of documentation that you can filter on the left:

As far as I can tell, it only searches against the latest version of the reference docs though. If you click a system.string result, you'll see the latest docs for it. You'll have to pick the dropdown version of another version when you get there if you want something different.

Take-aways

I like using the basic model of:

• Conceptual docs are not versioned (but might have version specific notes in them)
• Reference docs are versioned and have a way to switch between versions
• Conceptual docs and Reference docs have different TOC trees for navigation (i.e. feel like different subsites)
• Search searches all conceptual docs and the current version of reference docs, with ways to filter the results to either if you want