I joined the Spyder team almost two years ago, and I never thought I was going to end up working on docs. Six months ago I started a project with CAM Gerlach and Carlos Cordoba to improve Spyder’s documentation. At first, I didn’t actually understand how important docs are for software, especially for open source projects. However, during all this time I’ve learned how documentation has a huge impact on the open-source community and I’ve been thankful to have been able to do this. But, from the beginning, I asked myself “why am I the ‘right person’ for this?”

Improving Spyder’s documentation started as part of a NumFOCUS Small Development Grant awarded at the end of last year. The goal of the project was not only to update the documentation for Spyder 4, but also to make it more user-friendly, so users can understand Spyder’s key concepts and get started with it more easily.

One of the main ideas for this project was to create a series of short video tutorials, explaining the basic functionality of Spyder and its most important panes, allowing users to learn how to use Spyder faster and easier.

Carlos Cordoba, our lead maintainer, thought I was the perfect person for this project because of my “good communication and organization skills”, my “clear and fluent English” (his words) and my previous experience at video editing and recording, which I actually gained by recording singing videos during my “YouTuber” phase.

I’ve always been interested in education and worked as a tutor for several years learning different tools, gaining experience on how to teach and questioning the effectiveness of current educational methods. This was the first reason why I got interested in this project. For me, documentation is just a fancy way of saying “educating people on using software”. The challenge here was not recording and editing the videos (which was actually a pretty arduous task), or planning the content for them; the real challenge was to make an impact in such a way that users could find documentation actually useful.

When users start to use a new IDE, or any new software, they usually refer to its documentation, which sometimes doesn’t give enough tools for them to start from zero. This was, then, the whole purpose of the tutorial videos. Spyder’s documentation was already very complete in terms of explaining all the features and cool things you can do with each of its panes. However, if I’m a completely new user and I don’t even know how to open it, where do I start?

I planned these videos as a series of progressive steps that can get users from zero experience to actually working with Spyder. Hence, I divided the videos into three sections, “First Steps with Spyder”, “Working with Spyder”, and “Building Projects with Spyder”. Each section builds on the one before in a way that they are clear enough so that users can find their way through Spyder without knowing anything about it.

The “First Steps with Spyder” section, live now on our YouTube channel, has three videos that provide a starting point for new users before they even open Spyder for the first time. The first tutorial covers different ways of opening Spyder, the basics of using its interface and an introduction to its four main panes, along with a quick look at the others so that users can get familiar with how Spyder is organized.

In the second video, users can learn the basics of using Spyder’s four main panes. The goal is that after this video, users are able to open and edit a file in the Editor, run a script and find the output in Spyder’s IPython Console and execute basic Python commands. They should be able to interact with the Variable Explorer to browse and edit the objects in the console, and use the Help pane to get documentation in two different ways.

The third video is meant to show users how to customize Spyder’s interface to start working with it in the way they feel more comfortable according to their preferences. It teaches users how to change the font and the theme of Spyder and rearrange its panes to display only the ones that they want such that it is easier for them to work.

After these three videos, I learned that one of the most important things for writing documentation, more than having a lot of experience with the software, is empathy. Usually being a developer makes it hard to put yourself in the position of a user and understand exactly what a user needs. Now, I realize that this is what actually makes me the “perfect person” for the project. As a junior developer, without as much experience with Spyder, I was able to think more like new users and develop content in a way that they feel closer to us developers. In the end, as Melissa said in her blog post, I learned writing documentation is also a way of building community.

I hope these videos are really useful, and I look forward to continue finding ways of making the open source community better.

Happy Spydering!

Comments