Docs Review: Wizard Notes, Schema & Broken Links

Hey everyone,

Let's dive into a comprehensive review and update of our documentation, focusing on key areas like Wizard notes, schema changes, and those pesky broken links. Our goal is to ensure our documentation is accurate, consistent, and user-friendly. Here’s a breakdown of the tasks at hand:

1. Wizard Notes Consistency

Wizard notes are crucial for guiding users through complex processes within our pipelines. Ensuring consistency in their placement and presentation is paramount. When we talk about Wizard notes, we're referring to those helpful snippets that pop up to guide users through the more intricate parts of our workflows. Think of them as breadcrumbs, making the user journey smoother and less confusing. The goal is to unify the look and feel of these notes across all documentation. Sometimes, a simple one-liner will do the trick, offering a quick tip or clarification. In other cases, particularly in sections like deployment, a more detailed dropdown note might be necessary to provide comprehensive guidance without overwhelming the user. It's about finding the right balance between being informative and concise.

Here's what we need to address: First, let's comb through the documentation to identify all instances where Wizard notifications are required, especially beyond the footer. We need to ensure that every relevant section has a Wizard note to guide users effectively. Next, consistency is key. We need to standardize the appearance and style of these notes, ensuring a unified look and feel across all documentation. This includes using consistent formatting, font sizes, and color schemes. We should establish clear guidelines for when a one-line note is sufficient and when a more detailed dropdown note is necessary, particularly in complex sections like deployment. For one-liners, we should aim for brevity and clarity, focusing on providing essential information in a concise manner. Think of them as quick tips or reminders that help users stay on track. For dropdown notes, we should provide more detailed explanations and step-by-step instructions, breaking down complex processes into manageable steps. These notes should be comprehensive but also easy to follow.

Ultimately, the goal is to make our documentation more user-friendly and accessible, empowering users to navigate our pipelines with confidence. By standardizing Wizard notes, we can create a more consistent and intuitive experience, reducing confusion and improving overall satisfaction. Let's work together to ensure that our documentation is not only informative but also a pleasure to use.

2. v6.1.0 Protocol Schema and Steps Review

Next up, is a thorough review of all protocols within version 6.1.0 for all pipelines. This involves meticulously matching the schema and steps outlined in the documentation with the actual implementation. Accuracy is key here. We need to make sure that what we've documented aligns perfectly with the live system. This process ensures that users have accurate and reliable information to work with. Let's start by gathering all the relevant documentation for version 6.1.0, including protocol specifications, schema definitions, and step-by-step guides. Then, we'll need to systematically compare each protocol's schema and steps with the corresponding implementation in the pipelines. This involves verifying that all fields, data types, and relationships are accurately documented and that the steps outlined in the documentation match the actual execution flow. We should pay close attention to any discrepancies or inconsistencies that may arise during the comparison. These could be errors in the documentation, bugs in the implementation, or simply areas where the documentation needs to be updated to reflect recent changes. For any discrepancies found, we'll need to investigate further to determine the root cause and implement the necessary corrections. This may involve updating the documentation, fixing bugs in the code, or both.

It's essential to keep track of all the changes made during this review process, including the discrepancies found, the corrections implemented, and the rationale behind each change. This will not only help us ensure the accuracy and consistency of the documentation but also provide valuable insights for future documentation efforts. By conducting this thorough review, we can significantly improve the quality and reliability of our documentation, making it an invaluable resource for users of our pipelines. This will not only enhance user satisfaction but also reduce the likelihood of errors and improve overall efficiency. Let's work together to make sure that our documentation is as accurate and up-to-date as possible.

3. Broken Link Identification and Fixes

Time to hunt down and fix any broken links lurking within our documentation. Broken links can be a major source of frustration for users, leading to dead ends and a negative user experience. Our goal here is to ensure that all links within the documentation are working correctly, guiding users seamlessly to the information they need. We need to systematically test each link in the documentation to identify any that are broken or outdated. This can be done manually or by using automated link-checking tools. For each broken link found, we'll need to determine the correct target URL and update the link accordingly. This may involve searching for the intended content on the web or consulting with subject matter experts to identify the appropriate resource. In some cases, the content may no longer be available, in which case we'll need to remove the link or replace it with an alternative resource. It's important to not only fix the broken links but also to prevent them from occurring in the future. This can be achieved by implementing regular link-checking procedures and ensuring that all new documentation is thoroughly vetted for broken links before it's published.

Furthermore, it's essential to maintain a comprehensive list of all links in the documentation, including their target URLs and the pages where they appear. This will make it easier to identify and fix broken links in the future. By proactively addressing broken links, we can significantly improve the user experience and ensure that our documentation remains a valuable and reliable resource. This will not only enhance user satisfaction but also improve the overall credibility of our documentation. Let's work together to keep our documentation free of broken links and ensure that users can always find the information they need.

4. Documentation Content Optimization

Let's optimize the documentation content by weeding out any deprecated stuff. This means removing or updating any information that is no longer relevant or accurate, ensuring that users are presented with the most up-to-date and useful content. We need to identify any sections of the documentation that contain outdated information, such as references to deprecated features, obsolete procedures, or incorrect data. This may involve consulting with subject matter experts, reviewing release notes, and comparing the documentation with the current state of the system. For each deprecated item found, we'll need to either remove it from the documentation or update it to reflect the current state of affairs. This may involve rewriting sections of the documentation, adding new content, or revising existing content. It's important to ensure that all changes are clearly documented and that users are informed about any updates or removals. We should also consider archiving or preserving the deprecated content in a separate location, so that it can still be accessed if needed. This will allow us to maintain a clean and up-to-date documentation set while still preserving the historical record.

Furthermore, it's essential to establish a regular review process to identify and remove deprecated content on an ongoing basis. This will help us keep our documentation fresh and relevant and ensure that users are always presented with the most accurate information. By proactively optimizing the documentation content, we can significantly improve its usability and value, making it an indispensable resource for users of our systems. This will not only enhance user satisfaction but also reduce the likelihood of errors and improve overall efficiency. Let's work together to keep our documentation lean, mean, and up-to-date.

5. RTD Flyer Doc Sets Versions

Finally, let's decide which doc sets versions should be displayed in the flyer at Read the Docs (RTD). Currently, we have five versions showing, and the question is whether we should streamline this to only show the latest 6.x version, removing 6.0.0. What about the older versions like 3.x, 4.x, and 5.x alongside the latest 6.1.0? This is where your input, @pphector and @MareikeJaniak, is highly valued! I think it's a good idea to limit the number of versions displayed in the RTD flyer. Having too many versions can be confusing for users, especially if they're not sure which version is relevant to them. By focusing on the latest versions, we can ensure that users are always directed to the most up-to-date and accurate documentation. Regarding the specific versions to display, I think it makes sense to keep the latest 6.x version (e.g., 6.1.0) and remove 6.0.0, as it's likely outdated. We should also consider keeping the older versions (3.x, 4.x, and 5.x) available, as some users may still be using those versions. However, we could potentially move them to a separate section or archive them in some way to avoid cluttering the main documentation page.

Another approach would be to provide a clear indication of which versions are actively supported and which are no longer maintained. This would help users make informed decisions about which documentation to use. Ultimately, the goal is to strike a balance between providing access to historical documentation and ensuring that users are directed to the most relevant and up-to-date information. Your input on this matter would be greatly appreciated! Please let me know your preferences, and I'll take care of the rest. Thanks, everyone, for your help in keeping our documentation top-notch!

For more information about documentation best practices, check out this article on MDN Web Docs.