This can be slotted under "How-To Guides" in a subsection on building for Ubuntu 14; it's explicitly referenced from the main README.

it's explicitly referenced from the main README.

Yes, that reference in the README needs to be deleted too. 16.04 LTS, 18.04 LTS and now 20.04 LTS should work. I really should've submitted that PR first; let me do that now.

PR deleting references to Ubuntu 14.04: #32010

I wonder if the distinction between "topic" and "reference" guides makes a difference for readers; they seem difficult to separate as both delve in-depth into specific areas. Some might focus more on design ("high-level"?) than implementation, but naturally the two bleed into each other. Merging these categories would allow many of these documents to be slotted into their proper places above.

I'm assuming you already read https://documentation.divio.com/introduction/.

they seem difficult to separate as both delve in-depth into specific areas

Perhaps it is useful to reemphasize the difference.

• a topic guide explains things. It is not intended to be exhaustive.
• a reference guide is intended to be exhaustive, only doing a minimal job as explaining things (linking to the topic guide as applicable). Consider something like the ABI, or semantics of SIL. Those need a solid reference which can be browsed quickly, without having to re-read explanations of things, which you probably already understand.

You can also see this distinction in Racket's language documentation:

• Guide: https://docs.racket-lang.org/guide/
• Reference: https://docs.racket-lang.org/reference/

Some might focus more on design ("high-level"?) than implementation, but naturally the two bleed into each other.

Design vs implementation is a different axis. You can have all of the following combinations:

• design + topic guide: changes to the design may need to be reflected in the topic guide, depending on how pervasive the change is. If a new very niche SIL instruction is added, it probably doesn't need to be explained if the semantics definition in the reference guide is enough.
• design + reference guide: changes to the design MUST be reflected in the reference guide. Consider adding a SIL instruction; it's semantics should be documented in the reference guide.
• implementation + topic guide: gives an overview of different moving parts. E.g. a high-level tour of the type-checker.
• implementation + reference guide: difficult to maintain since the implementation will be changing often, but doable with some discipline. Say we have a reference for all the typing judgements in sequent notation and link to functions in the source that they are implemented in.

Merging these categories would allow many of these documents to be slotted into their proper places above.

While that is a tempting thought, I think the fact we have this mix-up in a handful of places is not, by itself, a solid justification for merging the two categories. In fact, much of the documentation we have avoids this mix-up in the first place! It's not perfect separation like oil and water, but it's mostly clear for a lot of the existing docs.

I think not merging the two makes it clear what components are in need of a reference guide and what components are in need of a topic guide.

I'm not sure if it is the terms "topic guide" and "reference guide" that are creating confusion? Maybe I should rename it to "explanation" and "reference"?

Thank you for reminding me about the four categories you're working with here. I like your points about what might fall under what category. It's certainly the case that there are some documents that aim to be exhaustive and others that do not.

I guess my point here is that, in the case of certain topics, the dividing line isn't so neat. Take the analogy given in the source that you cite:

How-to guides: (analogy) a recipe in a cookery book
Reference: (analogy) a reference encyclopaedia article
Explanation: (analogy) an article on culinary social history

An encyclopedia entry on cooking will most definitely include a section on culinary history. In fact, the exact same text that goes into an article on culinary history would not be out of place in the encyclopedia article, if length requirements were met.

If, as part of a 'discursive explanation' of a topic, there is the need for an exhaustive table or list for adequate explanation; or if, as part of creating an exhaustive list, some 'discursive explanation' is needed for one particular entry, then I would think it's fine to go ahead and incorporate that information without splitting the document into two--as long as there's a prevailing purpose to the document.

Certainly, if one document is trying to serve two purposes, then I see a role for pulling it apart. I suppose what you're indicating here is that some of these documents fall under that scenario.

Anyway, big picture, my hypothesis is that the major barrier to effective contributions are the huge differences in skill level/familiarity:

• I think many who are motivated to contribute can't figure out where to start;
• many who do start by, say, correcting typos are motivated to fix bugs, but can't figure out how to compile and test their code (or perhaps even how to set up a local copy of the repository);
• many who do manage to start fixing bugs to the standard library don't have an effective workflow that allow them to work on larger changes that touch more than one part of the code base;
• many who do figure out how to add features to the standard library can't figure out how to contribute to the compiler: AST? Sema? SIL? where do I start?.

In parallel, the documents here are addressed to audiences of very different backgrounds. Some will make sense only to those who are elbow-deep in the compiler; others are explanatory texts useful even for Swift users who have no interest in contributing to the project at all.

So, to sum up, I think I've misunderstood a bit the categories you're going for here. While there are some parallels in terms of which document type is paired with which audience (as your cited source says, "Tutorials" are like teaching a small child how to cook), it doesn't segregate cleanly; how-tos and explanations can certainly range from one end to the other in expertise and interest.

By contrast, I would argue that the most salient axis along which to divide the documents is based on which audience the document is addressed to; i.e., what is their interest in the topic--using/teaching/documenting a feature? fixing bugs in the feature? making changes to the design of the feature?--and what is their existing knowledge level. This is why I commented below that perhaps "how to build the Swift compiler" and "how to dump and analyze optimization counters" don't go together.

In a perfect world, rewriting documentation to fit nicely into each of the four categories you outline would be great, but I think the biggest difference we could make is making a clearer distinction in terms of audience interest and skill level, and targeting the documentation appropriately.

The source you cite doesn't seem to consider this at all, because in most cases (such as documentation for a specific JavaScript library), the audience is a much more focused one and these problems don't really arise (they are going to be JavaScript users who need the functionality provided in the library, and they are going to be interested in how to use the library).

Put another way, the source you cite uses the analogy of different kinds of information for essentially the home cook, from tutorials for children to references for adults. But here, the documentation has to span the range from "how to hold a knife for those who can't read yet" to "the chemistry of molecular gastronomy for Michelin-starred chefs." In that scenario, separating "kitchen tools" from "molecular gastronomy" might be undertaken first, before separating the how-tos and references about kitchen tools.

I'm not sure if it is the terms "topic guide" and "reference guide" that are creating confusion? Maybe I should rename it to "explanation" and "reference"?

FWIW, I think "explanation" and "reference" make the distinction significantly clearer.

I think @xwu's comment about considering skill level/intended audience is really important, but I don't think most of it is actionable right now. IMO almost none of the current documentation is "beginner level". That's not to say we shouldn't think about how entry-level tutorials, etc. will fit in with the other docs once we've written them, but I'm not convinced we should attempt to divide the existing docs by skill level because most of them assume the reader is quite familiar with the compiler internals already.

Once there's a larger library of entry-level content, I do think that deserves it's own category so there's one place we can point prospective contributors to that doesn't involve lots of searching. Once somebody moves beyond starter bugs, I've found depth it's far easier to specialize in one area of the compiler rather than trying to understand everything at once. I think that's the point at which the proposed organization is more useful than attempting to gauge the difficulty of material, which is inherently subjective.

FWIW, I think "explanation" and "reference" make the distinction significantly clearer.

Thanks, I'll use the term "explanation" instead of "topic guide" from now on. (Will add a commit to fix this.)

Let me explain my thought process (this is very long, sorry!) before responding to specifics. The categorization of documentation and the new pieces of documentation I'm working on are together intended to serve several purposes:

1. Make finding relevant docs easier, for beginners, highly experienced developers, and people somewhere in between.
2. Make maintaining docs easier:
   a. Make it easier to identify gaps in the docs which could be addressed.
   b. Make it clearer where a new chunk of documentation should be added. If this new documentation gets added in a not-so-great place, that makes it more difficult to find for anyone else apart from the person who added it and the one who reviewed the PR.

For beginners, I think the important thing is to have a clear path through which we can guide people. This is the intention of the GettingStarted.md guide. I don't think that's going to be sufficient (as you mentioned, it's still not clear which component one should contribute to, or which StarterBug one can work on), but it's a start.

2b. is particularly important too. Often, it is tempting to add little nuggets of information next to other information which is related, even thought there is a category difference (how-to vs explanation, for example). This creates the problem you see in CompilerPerformance.md, where the explanation for the different compiler modes is otherwise put in the middle of what is a mixture of a how-to and an explanation for measuring compiler performance.

At this point, it is worth asking: what trajectory to do we expect/want new contributors to take? IMO, there are roughly three stages to it (I think this mostly matches up with Owen's perspective):

1. Project familiarity: How to get things up and running and a bird's eye view of the project as a whole.
   This will be served by GettingStarted.md + CompilerArchitecture.md to an extent.
2. Subsystem familiarity: How to solve starter bugs in a subsystem and have a basic mental model of how things roughly fit together in that subsystem.
   As Owen pointed out, we need more beginner-friendly material here. We can also improve our existing Explanations (I'm going to use this term instead of "Topic Guides"). If we have a beginner-friendly tutorial for an individual subsystem, we can suggest some follow-up resources at the end, say in a "Next Steps" section.
3. Subsystem expertise: Gain more in-depth knowledge and tackle more challenging tasks.
   I think this is something that probably needs to come through experience, reading doc comments and more of the source code.

Becoming an expert (3) is a more nebulous goal compared to making someone familiar with the basics, so I'm not focusing on this right now. My focus right now is on 1 and after that 2.

With this perspective, here's how I see the goals and non-goals of the index (as a whole):

1. Non-Goal: Provide a clear trajectory for a beginner on how to understand the documentation. Instead, I think this goal would be much better served by the combination of the new getting started guide (which will be linked from the readme), and tutorials (I don't have any concrete plans here at the moment, but we should have these!). These two aspects should together make it possible for a beginner to go from 0 to some level of subsystem familiarity, after which they can read the high-level documentation for individual subsystems.
2. Goal: Make it easier for someone to identify if some piece of documentation is missing, for better prioritization of what needs to be worked on.
3. Goal: Make it easier for someone with mid-high level of experience to find relevant documentation.
4. Goal: Make it clearer where new documentation should be added; whether it should be added to an existing file or a new one should be created.

Given all that background, let me respond to specifics:

it doesn't segregate cleanly; how-tos and explanations can certainly range from one end to the other in expertise and interest.

That's an intentional choice, for the following reasons:

1. Many topics do not really have any notion of expertise built-in. Expertise here, I think, is short-hand for "you need to know X before you can understand Y". That said, I do think we need to do a better job of articulating "suggested pre-requisites" or "suggested co-requisites". For example, if you are writing documentation on the constraint solver, the type-checker overview would be a suggested pre-requisite. For the type-checker overview itself, the request evaluator document would be a suggested co-requisite. IMO, classifying things into categories based on experience levels is too broad of a brush stroke.
2. Because the process is quite subjective, I think it would make finding and organizing thing more difficult.
   a. Search: There's a risk of almost everything getting lumped into an "intermediate category", which ends up making search difficult.
   b. Organizing: Say a beginner was reading some beginner-level explanation and submitted a PR to add a how-to in the middle of the explanation. Now, this how-to might be broadly useful, but it being buried in the middle of an explanation makes discoverability harder. The alternative of linking to (a specific subsection of) a how-to guide has better discoverability IMO, while accomplishing the same goal of highlighting "hey, here's this how-to-do-X you might find relevant" in context.

Certainly, if one document is trying to serve two purposes, then I see a role for pulling it apart. I suppose what you're indicating here is that some of these documents fall under that scenario.

Yes, that's what I'm trying to indicate. CompilerPerformance.md is a very clear example of that; it's trying to do a LOT all in one place.

Anyway, big picture, my hypothesis is that the major barrier to effective contributions are the huge differences in skill level/familiarity: [..]

I mostly agree with the points you've laid out here. People with different levels of expertise have different needs. As I outlined above, I don't think the index is the best tool for that job. Instead, the index can focus on a different set of goals and accomplish them well, and we should have other forms of documentation (tutorials and beginner-friendly explanations are two examples) which specifically address the needs of beginners. Certainly, this beginner-specific documentation will take time to build, but I think that's a worthwhile goal to pursue, and a better long-term bet, instead of having the index shoulder those responsibilities too, on top of the other goals I mentioned.