Reorient docs toward a task-based structure

[colindean]

Verification

• This issue's title and/or description do not reference a single formula e.g. brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.

Provide a detailed description of the proposed feature

The Docs track of the AGM agreed on an observation that many of our docs could be reorganized to prioritize objective task completion instead of often lengthy system or operations descriptions.

Contrived examples, totally not intended to be actually used:

Current: System/ops description	Proposed: Task-oriented title
Taps	Create and manage collections of Formulae and Casks with Taps Hosting a third-party repository for Taps
brew livecheck	Implementing an effective livecheck Choose a livecheck strategy

This would be a large body of work and may necessitate breaking up large documents and ensuring there is a table of contents on some pages.

What is the motivation for the feature?

While seasoned maintainers may know exactly where look for help on a subject having seen it in the docs before and needing a refresher, folks new to the docs or infrequent users may benefit from a browsable structure that presents a selection of common tasks, perhaps collected by area.

How will the feature be relevant to at least 90% of Homebrew users?

All maintainers benefit from clear documentation, and most users looking for help would benefit from a more browseable set of titles and headers that are more likely to align with their current task.

What alternatives to the feature have been considered?

We may be outgrowing our current documentation system, but this work should not yet necessitate such a move.

[alebcay]

Reminds me of https://diataxis.fr/. TLDR:

• Tutorials (learning-oriented practical activity)
• How-to guides (goal-oriented directions which guide through a problem or towards a result)
  • Lots of (outdated) third-party video and blog material out there in this area
• Reference guides (information-oriented technical descriptions of mechanisms and operation)
  • RubyDoc
  • Formula Cookbook leans somewhat in this direction
• Explanation (understanding-oriented discursive treatment of a subject)
  • Whitepapers, blog posts, etc.

Not all four quadrants necessarily make sense in Homebrew's context, but I think it's a useful framework for thinking about what kind of docs there could be.

[colindean]

Diataxis is an inspiration!

[MikeMcQuaid]

Good idea!

Taps

• Create and manage collections of Formulae and Casks with Taps
• Hosting a third-party repository for Taps

If we do a rename like this: let's try really hard to ensure we have redirects to not break existing links.