Provide a solution document for #250

"Documentation search categories are not standartized"

Fixes #250

solutions/documentation/search-categories.md

@@ -0,0 +1,88 @@
+# Search categories
+
+The [documentation for Raku](https://docs.raku.org) website supports search feature:
+the user can look up terms by text to navigate to relevant documentation pieces describing
+the term.
+
+A single index entry consists of: a name (optional), a term and a category (optional).
+
+* The name specifies what is rendered on a page where an index entry is placed (or nothing to render if absent)
+* The term specifies what the user has to specify as a search query to navigate to this index entry
+* The category is used to group search results from a common domain. If none is given, the default value
+  is 'Reference'
+
+In Pod6 markup language used in [the documentstion](https://github.com/Raku/doc) an index entry
+is written as:
+
+```
+# Common
+X<name|category,thing>
+# Variations
+X<|category,thing>
+X<|thing;thing;thing>
+X<|category,thing;category,thing>
+```
+
+The categories shown in the search are driven by the sources, which means
+that if e.g. a contributor makes a mistake and writes:
+
+```
+X<name|thing,category>
+```
+
+Then the `category` term will be simply indexed under `thing` category,
+even if the search category `thing` does not make any sense to the reader.
+
+This format is prone to misunderstanding by the documentation contributors and
+search categories are often specified incorrectly. Not only this, but prior to this
+document there were no standard describing a consistent list of categories,
+leading to gathering various inconsistent category naming schemes, confusing readers.
+
+# Solution
+
+To address two problems described in the last paragraph, I propose to follow these steps:
+
+1. Establish a list of supported search categories, see Appendix A.
+
+2. Write a test for the documentation sources to gather all present index entries
+   and checks them against the approved categories list. The test passes when
+   all index entries adhere to the approved categories.
+
+3. Gradually adapt current documentation index entries to pass the test.
+
+# Outcomes
+
+* An organized list of categories makes it easier for the user to understand
+* A solid state of search categories makes it easier for the contributor to index items into correct
+  categories
+* Possible separate documentation search frontends get a much cleaner set of categories to search by
+
+# Appendix A: Search Categories
+
+This list is made with a couple of styling rules in mind, those are:
+
+* Titlecase over lowercase (`Subroutines` over `routines`)
+* Plural over singular (`Subroutines` over `routine`)
+* Categorize both Raku language standard library API (`Types`, `Subroutines`) as well
+  as language-related topics and terms (`Language`, `Syntax`) grouped
+
+The standard list is:
+
+- [ ] `Types`
+- [ ] `Modules`
+- [ ] `Subroutines`
+- [ ] `Methods`
+- [ ] `Terms`
+- [ ] `Operators`
+- [ ] `Adverbs`
+- [ ] `Traits`
+- [ ] `Phasers`
+- [ ] `Syntax` (various bits of language syntax explained at meta-level)
+- [ ] `Regex` (everything related to regex)
+- [ ] `Control flow` (everything related to control flow)
+- [ ] `Raku` (syntax bits such as quoting, literals, identifiers)
+- [ ] `Variables`
+- [ ] `Reference` (default category for general reference)
+- [ ] `Language` (language-related topics)
+- [ ] `Programs` (program writing-related topics)
+- [ ] `Foreign` (for terms from other languages and migration guides)