Improving the Docs: Workbench

Workbench is a user-friendly open-source tool designed for hands-on exploration of GNOME technologies. It caters to both beginners and seasoned developers. With an extensive library featuring over 100 examples, it offers practical learning experiences.

The live GTK/CSS preview and support for JavaScript, Rust, Python, and Vala makes it perfect for trying and testing GNOME technologies.

In this article, we will analyze the available documentation for Workbench and explore ways to improve it. Let’s dive in.

Current Documentation Assessment for Workbench

Currently, Workbench's documentation library only includes a README and contributing file, both available on its GitHub repository. Looking through both files, these are some of their strengths:

1. Clear Purpose Statement: The README explains Workbench's purpose: experimenting with GNOME technologies for beginners and experienced developers.

2. Feature Highlights: Clear highlighting of key features such as live GTK/CSS preview, example library, and multi-language support.

3. Testimonials: Real user testimonials add credibility and emphasize the positive impact of Workbench.

4. Structured Contribution Guide: The guide is well-structured, providing a clear path for potential contributors.

5. Development Setup Instructions: Detailed instructions on setting up the development environment using GNOME Builder are beneficial.

The areas listed above are essential. However, there are some downsides to the current documentation. For instance, the README doesn’t provide in-depth information on how to use Workbench, which can be an obstacle for beginners.

Additionally, the documentation is poorly organized and difficult to navigate, leading to frustration and abandonment.

User Feedback Analysis on Workbench

To better understand the challenges faced by users, we analyzed Workbench’s GitHub repo for issues raised, specifically documentation-related. We found that users are struggling with the following:

• Lack of Getting Started Section: Some users have raised concerns about the absence of a getting started section and suggested improving documentation. This feedback highlights the need for beginner-friendly and detailed documentation.

• Document Internal Variables: Users are experiencing difficulties accessing internal variables like workbench.window or workbench.builder. Lack of documentation on these elements poses challenges, especially for those without access to the source code. Addressing this would significantly enhance the accessibility and usability of Workbench.

• Improve Contributor Experience: Issues related to the contributor experience include suggestions for a PR template. Improving the contributor experience through streamlined processes and clear documentation is essential for fostering community engagement.

• Document GNOME 45 Changes: The call to review GNOME 45 changes and incorporate relevant updates into the Library highlights the importance of keeping the documentation updated. It ensures users have accurate and up-to-date information about Workbench and its compatibility with GNOME updates.

Apart from the issue listed, there are other observations we made that could greatly impact Workbench’s documentation. It lacked some essential elements of a README file. They are:

1. Installation Guide: The existing documentation could benefit from a more detailed and user-friendly installation guide. Clear step-by-step instructions ensure that users, especially newcomers, can easily set up Workbench without encountering obstacles.

2. Community or Support Channel: A designated section indicating where users can seek support or engage with the Workbench community exists in the contributing file rather than the README file.

3. Requirements: Clearly outlining the prerequisites and system requirements ensures users have the necessary tools and environments in place before diving into Workbench. This helps avoid potential difficulties.

4. Usage Instructions: While the README provides an overview, incorporating more detailed usage instructions or examples would be beneficial.

5. Visuals/Images: Adding visuals such as screenshots or GIFs demonstrating Workbench in action enhances the documentation's clarity.

6. Progress Status: A section indicating the project's current status, milestones, or future roadmap is not present. Including this information provides users with insights into the project's development trajectory, fostering transparency and managing user expectations.

From all these issues listed, it’s evident that Workbench’s documentation needs a thorough revamp. We’ll look at ways for improvement next.

Proposed Improvements for Workbench

To address the identified challenges and improve the overall documentation experience for Workbench, here are some proposed improvements:

• Comprehensive Getting Started Section: Introduce a getting started section in the documentation, offering step-by-step guidance for users at various skill levels. This section will provide clear instructions on installation, setup, and initial usage, ensuring a smooth onboarding process.

• Detailed Usage Instructions: Expand the usage instructions in the README, providing in-depth insights into different features, workflows, and best practices.

• Structured Documentation Navigation: Reorganize and structure the documentation for easy navigation. Use clear sections, headings, and a table of contents to streamline user access to specific information.

• An intuitive layout will reduce frustration and encourage users to explore the documentation thoroughly.

• Incorporate Visual Elements: Enhance the clarity of the documentation by incorporating visuals such as screenshots, GIFs, and diagrams. Visual aids will provide users with a visual representation of the tool's features, making it easier to follow instructions and understand concepts.

• Internal Variables Documentation: Address user feedback regarding difficulties in accessing internal variables. Provide comprehensive documentation on key internal elements.

• Improved Contributor Experience: Implement suggestions for improving the contributor experience. This includes the addition of a PR template in the contributing guide.

• Documentation on GNOME Version Changes: Regularly update the documentation to align with the latest GNOME version changes. Ensure that users have access to accurate and up-to-date information about Workbench's compatibility with the latest GNOME updates.

• Include Essential README Elements: Integrate missing elements into the README file, such as system requirements, and a project progress status. These additions will make the README a comprehensive resource for users and contributors.

• Link to Contributing.md in the Readme: Establish a clear link to the contributing.md file directly within the README. This will guide users and potential contributors seamlessly between the essential documentation sections, promoting a more accessible documentation structure.

• Community/Support Channel in Readme.md: Improve the visibility of the community and support channel information from the contributing.md to the readme.md. This relocation ensures that users can easily find and engage with the Workbench community directly from the main documentation.

  Improved accessibility to support channels encourages collaboration and assists when needed.

• Additional Docs Section: Introduce a dedicated section in the README highlighting additional documentation resources. This section can include links to in-depth guides, tutorials, or any supplementary materials that offer users a more comprehensive understanding of Workbench's functionalities.

• Ways to Contribute Section in Contributing.md: Introduce a dedicated section within the contributing.md file outlining various ways to contribute to the Workbench project. This can include guidelines for submitting bug reports, feature requests, and more.

After analyzing some tools similar to Workbench, it was found that both Testsigma and LambdaTest had no documentation issues and fewer overall issues on their GitHub repositories. This highlights the potential benefits that Workbench could gain from improving its documentation.

Conclusion

Workbench is a valuable tool for GNOME technologies, but its documentation faces challenges. Our analysis revealed gaps like the absence of a comprehensive getting started section and undocumented internal variables.

We further proposed improvements including a getting started guide and enhanced contributor experience.

Implementing these changes aims to boost usability, ensuring Workbench remains an accessible resource for developers exploring GNOME technologies. Improving the documentation is crucial to ensure continued usefulness and user satisfaction.