Guides section rework #152
Conversation
nrichers
added
documentation
|
Pull requests must include a description in the release notes section. |
1 similar comment
|
Pull requests must include a description in the release notes section. |
There was a problem hiding this comment.
my comments are for the new structure only (I know the content within pages is still placeholders).
The new structure looks very good - much easier to navigate and the content organization is a lot more helpful.
This structure will also make it much easier to add new topics and sections
|
Pull requests must include a description in the release notes section. |
|
One remaining item for this PR is to hide the content that isn't ready. Quarto does have support for conditional content, but not for entire topics, so we need to do a bit of work to hide content and keep track of what's been hidden: In the front matter
In _quarto.yml
Output changes Highlighted topics have been hidden.
|
|
Created backlog items for the missing placeholder content: https://app.shortcut.com/validmind/epic/2687?cf_workflow=500000037&ct_workflow=all&group_by=none&query=Author&vc_group_by=day 
|
Internal Notes for Reviewers
This PR introduces several incremental improvements to the "Guides" section and sidebar of our docs site. The best way to preview the changes is to compare the old and new sites:
Addresses:
Major changes
Minor changes
This PR does NOT cover all of the Guides section rework, more PRs will come (cf. placeholder topics with lorem ipsum text). But it is a prerequisite to future content updates and should enable us to have a better conversation about the content architecture for this part of our docs site. If this format works, I will start a similar PR for the "Developer Framework" section.
Notes on the original new "Guides" landing page rework — OLD, IGNORE
The issue: The current, sparse page makes it difficult to know what you should be doing after you have completed the Quickstart and there's not a good way to highlight the most important tasks. The left sidebar is your only method of navigating content but it's really just a long list of topics, divided by role. If I had perform a task on, say, model templates I would need to scan the sidebar or use the search.
The resolution: Add a new landing page that curates the most common or important tasks
by role, and then subdivide those tasks further into getting-started tasks and tasks you might perform more regularly. For example: if I am an admin, I should be able to see at a glance what I need to set up ValidMind for my organization. Or, if I'm a model developer, I want to know what I need to do get started with documentation projects, now with a better tie-in with our separate developer framework section.THIS HAS BEEN REPLACED, SEE ABOVEThe way this page is implemented is by taking the idea of Quarto document listings, tweaking the format to suit our purpose, and creating several smaller listing sections. This way, content updates in the topics listed here are automatically reflected in the listings which makes future maintenance easier.
If this format is well received, it could serve as a template for reworking the slightly awkward end-to-end workflow in the developer framework section (itself already an improvement over the massive flowchart we have in Miro, but the developer experience can be improved further).
Restructure the left sidebar
The issue: Our current sidebar tried to do what the new landing page does by superimposing a division by role, but within the limitations of a small sidebar that is not well-suited for the purpose. Additionally, we have some section headings that are not actually clickable topics which can make for an awkward user experience as you click around. It's currently the only way to find your way around the "Guides" section but it is not ideal.
The resolution: Sidebars work better when not overloaded. Let's restructure the left sidebar to facilitate navigation by product area or major feature, complementing the new landing page's role-based navigation of common tasks. This change also enables us to highlight product features that are designed to work across roles, such as collaboration between developers and validators. We can also indicate better what is a clickable topic and what is a HEADING by upper-casing the latter.
External Release Notes
A new landing page for the "Guides" section of our docs site now curates the most common tasks by roleto help you get up and running with ValidMind in a production setting. Additionally, a restructured left sidebar enables navigation of content by product area or major feature. Both of these changes make it easier to find the content relevant to you, whether it is for the role you perform or the product features you are interested in.