Developing Matplotlib Entry Paths Proposal
Introduction
Matplotlib’s project suggestion for this year’s Google Season of Docs involves creating content that helps introduce Matplotlib to new users. For Developing Matplotlib Entry Paths, I propose an alternative approach to that of current documentation. I am a new technical writer to the industry; however, my background is in education and education-adjacent fields. Technical writing and education have strong parallels that focus on producing content that empathizes and enables users to accomplish their tasks with the resources provided.
In this context, the Matplotlib documentation would benefit with improvement to empathizing with new users. Much of the material at the moment consists of randomized data and unlabeled visuals. These are excellent for quickly displaying the visuals and the features of Matplotlib. However, for the use case of someone new to Matplotlib, it is challenging to traverse the transformation of data to visuals.
A context in an expository approach is a solution to this obstacle. By writing a procedure through the lens of a real world example, we are demonstrating an understanding of the environment in which a user works. This improves the relationship the documentation and user have in terms of the reaching a goal or expectation of accomplishing a task.
A user has a consistent derived purpose, For example, a data scientist at a shoe company must present customer data to a team to illustrate shopping trends over time. In this situation, the user must learn to navigate Matplotlib and take advantage of the tools within the library to complete the task at hand.
With additional context to support the documentation, a new user may be more able to identify with the topic. The user’s derived purpose is parallel to the documentation. I hope to work towards the vision that Lead Developer Tom Caswell discussed in an interview in 2017 as “having someone who can actually write and has empathy for users, to go through and basically write a 200-page ‘Intro to Matplotlib’ book, and have that be the main entry to the docs.”
Alternative Approach of Expository Writing
The current documentation demonstrates the features of Matplotlib, i.e. the things a user is able to do with the library. For instance, a tutorial often follows the pattern that doesn’t involve an explanation of the underlying method.
{what the method does} → {parameters} → {returns} → {related links} → {examples}
Often with programming documentation and support, a user is recommended to run the code on their own to understand what happens. Although a programming mindset improves a user’s understanding of the topic, the learning curve for transformations has little supporting content. It can be an overwhelming challenge as documentation is limited.
Providing additional diagrams, images, or other visuals will help to create new learning opportunities. The structure below would also serve well as a template for new content. Also, the point of adding non-textual images or graphics could benefit from features like callouts and coachmarks. There are times where images are harder to navigate without indications of how or where the code is transformed into the output executed. I believe that there is a strong visual element missing that could foster a greater understanding of the topics.
{method explanation} → {expository use case/scenario} → {sample code} →
{parameters} → {returns} → {additional examples} → {informational topic/subject affinity links}
There is massive potential in this alternative approach of using expository writing for documentation. With users seeing a variety of concepts for transformations, they would be able to better identify the underlying strategies of developing visualizations to data. This knowledge can help users innovate and take advantage of the features as presented by examples based in realistic use cases.
As Matplotlib grows in popularity, consistency in ease of use and approachability are testament to the library’s reputation. These characteristics lend themselves to demonstrate patterns and common strategies that can surface not only within the code, but also within the documentation. If Matplotlib is straightforward and standard for users to program, as evident in its growing use and expanding resources, it can also be that way for technical documentation.
When users encounter problems, it’s common to use search in order to solve them. Rather than rely on search as the primary method of navigation, it can be more impactful to have users build their own curriculum within the documentation. In this sense, a user searches for a solution to their problem, then when they encounter another problem or would like additional information, they’ll make use of embedded and thorough links throughout.
This would involve a bottom-up architecture in the organizational system. For every topic within Matplotlib, a rich network of links to subject affinities as well as informational topics would help to build a robust network. Throughout this network, a user would be more likely to continue using the documentation as they navigate to their topic and explore more and more information related to that topic.
Obstacles
There are always challenges with a project as comprehensive and detailed as this. As a newer technical writer in the industry, I have limited experience using Sphinx and ReST to write documentation. I’m also a beginner when it comes to Matplotlib as well as Git. Tackling these four systems and getting comfortable with using them for collaboration and research will take time. I will need to delegate time during the community bonding phase and earlier to in order to build the necessary foundation for entry level paths. During this time, if I have issues with concepts and fundamentals, I will need to reach out to the community for additional support.
Coordinating collaborative efforts across time zones and over online platforms will take some adjustment as well. There are a variety of communication avenues that people all throughout the industry use, so it is a matter of making sure I am accessible and approachable in all mediums. I will be transparent in my prioritization of varying expectations throughout. Though I am only just starting out with taking on work such as this in the industry, I am invested in holding myself accountable and being open to feedback and criticism. I feel these qualities are valuable no matter the field.
Also, increasing usability testing is a section of documentation that I believe would benefit Matplotlib’s entry paths. Conducting surveys for usability regarding the content serves a purpose of providing a profile of a user, i.e. personas. Information such as a user’s experience, their industry, and troubleshooting history are valuable. These pieces help form the language behind the procedure. When writing meets readers at their level, content matures beyond acting as solely instructional.
Big struggles often lie with creating an ongoing practice of usability testing. It’s far too common to have had a single instance of testing, if done at all, during content development. Regular usability testing helps drive the narrative of the content. It would be my hope to setup a schedule or have recurring usability tests with the Matplotlib community.
Conclusion
I have a little experience using Python as well as Matplotlib in my free time. The amount I’ve taught myself over the last few months was with the support of the current documentation and my own curiosity. There were a handful of videos and mentors I’ve had in that time as well. I’ve still got much to learn and even more room for improvement as I build my own curriculum of programming that I’m interested in.
After seeing the ideas that Matplotlib and the community have for GSoD, I feel like it would be an excellent growing experience to improve on my skills as a technical writer and get the chance to learn more from the folks behind the scenes. I have felt that this Matplotlib project is both meaningful and something I am passionate about in ideology.
For working on an overhaul of the usage guide, my goal as a technical writer is to help users accomplish the tasks that they want to without being overwhelmed by the features available. I believe that the best documentation would continue to grow and adapt to users and allow for any user to navigate to their own solutions.