Should we combine the "guides" and "references" section in the documentation?

[sarayourfriend]

These super-sections do not have a very clear distinction to me. The guides section is specifically noted to be for setting up the local development environment but also includes information about our approach to logging, zero downtime deployment, how publishing images works (which can be deleted as is no longer relevant), amongst others. The "references" section has very little in it and the reason those documents are in a separate section from the "guides" isn't clear. Should we merge these super sections? If not, can we create a clearer definition/explanation of the "references" section?

[dhruvkb]

In my opinion the separation is about the end goal of the reader. If you want to know what something is, you go to the reference e.g. to know what the CI + CD workflow is and does. If you want to know how to do something you go to the guides e.g. to know how to set up the dev environment.

The documentation about the search algorithm belongs in the Reference section. The documentation about using the deployment workflows to trigger a prod release would go in the Guides section.

For another example, documentation about the logging workflow and the different places for the logs would be in the reference. How to write the logs and how to look for something in them would belong in the guides.

The "references" section has very little in it

Not having enough material in either section is due to a lack of documentation and not a fault of the organisational system.

the reason those documents are in a separate section from the "guides" isn't clear

Basically the guide section is a mix of types 1 and 2 and the reference section is type 4.

there are four distinct kinds of documentation - with four distinct functions. The four kinds of documentation are:

1. learning-oriented tutorials
2. goal-oriented how-to guides
3. understanding-oriented discussions
4. information-oriented reference material

Write The Docs

---

Considering the above points, there are two pieces of docs that I think have been wrongly filed or could use a rephrasing. These I believe contribute to the confusion of why these are separate categories.

• GitHub Contribution Practices § Choosing an issue is more about how to choose an issue and thus belongs in the guides, while the rest of the doc is a reference about our labels.
• Development workflow is meant to a be a reference about our process but the nature of process-documentation reads a lot like a guide.

[sarayourfriend]

Thanks for explaining that rationale, Dhruv. Do you think something like the documentation expanded in this PR would make sense to split between the guides and the references? Parts of it are "guides" (setting up the local environment) but the other part is reference (default custom event information).

Maybe it would help if all the guides were named in the style of "How to ..." or at least were connected somehow in that way. Then the "where to look" question is easier to answer. If I want to know "how to ..." then I look in the guides. Everything else is "reference" material.

[AetherUnbound]

For some further context, the book Docs for Developers describes a couple of different forms of documentation:

• Code comments - describes what the code in question does
• READMEs - single text file that summarizes a collection of code
• Getting started documentation - guides users through first impressions & first time user experience
• Conceptual documentation - helps users understand the concepts and ideas behind a service
• Procedural documentation - tutorials, how-to guides, anything from installation instructions to API integrations which shows readers how to accomplish a specific goal by following a set of structured steps
• Reference documentation - cause and effect, which actions produce which results, API reference/glossary/troubleshooting/changelogs

Not suggesting this as a way to structure our documentation, but rather as a way to think about different types of docs as we have this discussion.

[zackkrida]

This reminds me a bit of the "folder-by-type" or "folder-by-feature" debate in software directory structure. Like is it better to have code grouped by type:

├── controller
│   ├── analytics.fake
│   └── reporting.fake
├── model
│   ├── analytics.fake
│   └── reporting.fake
└── view
    ├── analytics.fake
    └── reporting.fake

or by feature:

├── analytics
│   ├── controller.fake
│   ├── model.fake
│   └── view.fake
└── reporting
    ├── controller.fake
    ├── model.fake
    └── view.fake

I personally tend to prefer by feature. I think we could have something like this using the currently-live pages as an example:

Proposed reorganization

• General setup guide
• Quickstart guide
• Frontend
  • Quickstart guide
  • Testing guide
  • Feature flags
• API
  • Quickstart guide
  • Testing guide
  • Authentication and Throttling
• Ingestion server
  • Quickstart guide
  • Testing guide
• Reference
  • GitHub contribution practices
  • Development workflow
  • Logging
  • Zero Downtime and Database Management
  • Search Algorithm
• Changelogs
  • API changelogs
  • Frontend changelogs
  • Ingestion server changelogs
• Openverse API Terms of Service

[zackkrida]

I'd like to try and draw some conclusions here. It looks like there's majority interest in restructuring to top-level stack directories. I'll ping folks who haven't explicitly chimed in on this format: @dhruvkb, @stacimc, and @krysal.

I'll create an issue for getting the docs more like this, and can remove/modify that issue if any new feedback comes in here.

[dhruvkb]

I'm biased towards guides and reference being separate top-level entities. Consider some more examples:

• Django
• DRF:
  
• Vue
  

But then again, these are singular libraries and not multi-stack monorepos so I can see why this layout might be more understandable and am more than happy to go along with this layout if that's the consensus.

[stacimc]

I would personally find it easier to find what I'm looking for in top-level stack directories. I think that might also be easier from a writing documentation standpoint (for me).

[sarayourfriend]

@dhruvkb Those are interesting examples, but they're all documentation for a single library. Openverse has four distinct and individually complex aspects of the full application stack. Each one could have a "guides" and "references" sub-section.

frontend
|- guides
|- reference

api
|- guides
|- reference

ingestion server
|- guides
|- reference

catalog
|- guides
|- reference

meta
|- documentation guides
|- how the stack is integrated
|- ??? etc

This at least disambiguates the references section and helps to collect all the relevant information for one application or another under a single heading. Right now you have to know to look in both places, even though you probably would land first in the "guides" section.

I like the idea of "guides" being "how do I ...". "How to write Openverse API tests." "How to write Playwright tests". These would be concise documents the list guidelines, linking to reference pages that document the tools we have available, like fixtures for API testing or utils for Playwright tests.

To me that seems like it would strike a balance between the distinction Dhruv is emphasising, and solve the difficulty that others have expressed with having guides and references at the top level.

[zackkrida]

I'm going to close this and discussion can continue as we prioritize this new issue: #1817

[zackkrida]

@panchovm I know you've been doing some information architecture work lately around w.org; any thoughts here?

[fcoveram]

Not really. You all fit the intended audience, and the discussion is already unrolling fruitfully. I rely on any outcome of this issue.

[zackkrida]

Created an issue for the outcome determined here: #1817