What we know:
Users don't always know the terminology or structure of OS Docs, which can make it difficult to find relevant information. Some users bypass the existing OS Docs search and use Google because they find it more successful.
Material for MkDocs is going into end of life and will no longer be maintained. Our current setup also doesn't give us insight into search behaviour - for example, what users search for - making it harder to understand and refine search over time.
Question
What is the smallest viable way to make OS Docs search more effective for users who may not know the terminology or structure of the documentation?
- Better search should give users a reasonable chance of finding and recognising relevant documentation using language that makes sense to them, without requiring them to already know OS terminology or OS Docs structure
We'll know the spike is done when
We can make a recommendation about what search approach to move to next, based on:
- What improving/upgrading our docs tooling could give us. Zensical is one option to explore, not a predetermined solution.
- Whether there are other proportionate search options worth considering.
- How well the options support the search experience described above.
- Whether/how they could give us insight into search behaviour to inform future improvements.
- The relative effort, complexity and ongoing maintenance involved.
Recommend a preferred option to move to, alongside 1–2 viable alternatives we could consider if the preferred option doesn't work out.
Out of scope: Selecting a documentation platform based on wider documentation needs, i.e. making contribution easier for non-technical users. These are recognised needs and should inform future work. If this spike identifies a platform decision that would significantly constrain those needs, flag this for further investigation rather than expanding the spike.
What we know:
Users don't always know the terminology or structure of OS Docs, which can make it difficult to find relevant information. Some users bypass the existing OS Docs search and use Google because they find it more successful.
Material for MkDocs is going into end of life and will no longer be maintained. Our current setup also doesn't give us insight into search behaviour - for example, what users search for - making it harder to understand and refine search over time.
Question
What is the smallest viable way to make OS Docs search more effective for users who may not know the terminology or structure of the documentation?
We'll know the spike is done when
We can make a recommendation about what search approach to move to next, based on:
Recommend a preferred option to move to, alongside 1–2 viable alternatives we could consider if the preferred option doesn't work out.
Out of scope: Selecting a documentation platform based on wider documentation needs, i.e. making contribution easier for non-technical users. These are recognised needs and should inform future work. If this spike identifies a platform decision that would significantly constrain those needs, flag this for further investigation rather than expanding the spike.