We intend to organize our documentation using a combination of curated links, tags, and folders.
Our general strategy for navigation should be to prioritize identifying why a reader is looking for documentation and based on that context attempt to guide them to what specific information they might be looking for.
Beginning with the home page we will work to provide a series of curated links to help guide readers to information based on their specific use cases with an eye towards supporting the mode of interaction they are looking for. This is our primary navigation option for members
Examples:
Prioritizing reader needs
These pages should avoid overwhelming readers and provide concise lists of prioritized links to useful documentation. These selections should be informed by research via direct member interviews , user surveys, support tickets, and documentation traffic metrics. Homepage and high level links can in turn link to other thematic selections of curated links to documentation pages. If the reader still hasn't found what they are looking for in the curated links these pages should guide readers towards more expansive thematic lists and additional ways to search for documentation based on keywords.
Some readers will know to search for specific keywords to find the information they are looking for. The names of services like e-mail, website, and video conferencing or specific software titles like Wordpress, Roundcube, and Jitsi. Just as some documentation pages can be related to more than one service or software they can be related to multiple keywords. Assigning one or more tags to a page can help readers find the documentation they are looking for through the search bar or through automatically generated lists. Use tags instead of folder names or paths to categorize documentation based on software , services, or technical keywords.
Our documentation should be written to follow a few specific forms or modes as suggested by the diataxis framework, tutorials, how-to guides, technical reference and explanation. These documentation forms are intenteded to be fixed, separate and distinct, so storing pages of each type within their own folder in our documentation path hierarchy is a natural fit. These folders paths are not meant to be the primary mode by which readers search or nagivate documentation although they could be explored that way. More importantly they are meant to help guide our writing style and structure for pages. If you are putting a page into the how-to folder, it should be written as a how-to guide! In practice, tutorials and how-to guides should also link to related technical reference and explanation pages as much as possible to offload that work to the appropriate page and give readers the option to explore more details.
Of the above forms and folders it is likely that pages in the how-tos folder will grow to be the largest in number. It may eventually be useful to further subdivide this content into subfolders. Historically our first impulse will be to create subfolders based on specific services. This overlaps with our intentions for using tags which may not be a problem itself but with folders and paths it returns us to a more difficult taxonomy issue that tags help us avoid, how exactly should we name these subfolders? For example /guide/email/ and /guide/web/ may seem like obvious choices for how-tos related to those general services or any related software. However consider how-tos related to the Nextcloud software... should these be called /guide/nextcloud/ , /guide/file-sharing/ ? Given that the Nextcloud platform itself aggregates several different apps each providing its own service like file-sharing,calendars,surveys, etc... how should we manage this? Don't do it We can avoid this problem for now by electing not to create subfolders until we have more clarity about how we want to proceed.