The new Spyder Editor documentation under the spotlights!
Published November 15, 2022
My journey with the Spyder IDE open-source project as a Google Season of Docs technical writer is approaching its final destination. It has been an incredibly rewarding yet challenging experience that helped me grow professionally and as a human being. I was privileged to join such a striving and committed community like Spyder, learn from its knowledgeable members, and contribute back to improving and expanding Spyder 5’s Editor documentation.
As an open-source software user, I have always felt frustrated when using software with out-of-date and unreliable user documentation. The lack of proper documentation, especially for newcomers, is a common yet critical issue in many open-source projects. Most of these projects offer a lot of information scattered everywhere and lack organization, which makes contributing to these projects terrifying, especially for people with no prior experience! That’s why I had a goal in mind to make contributing and using open-source software less intimidating and more convenient, which led me to the Google Season of Docs 21 and 22 programs.
During the past 6 months, I, my mentor for this program Stephannie Jiménez, and other community members have been working tirelessly to transform the current obsolete Editor docs and release them to users. The new documentation—hopefully—will provide the Spyder community with a reliable source of information while shedding the light and showcasing some of the IDE and Editor’s new and main features.
As already known, the Editor is one of the principal components of the interface in the Spyder IDE, after all, it is where all of the code is created, visualized, and executed. The newer versions of Spyder have introduced significant changes and improved some of the current IDE functionalities. Thus, making the documentation look irrelevant and outdated. Originally, the scope of this project was to update both the user and developer documentation for Spyder 5; however, updating the developer docs was descoped from this project due to unforeseen conditions and time limitations.
My writing approach: Familiarize – Write – Demonstrate
I developed the following approach to tackle the project’s tasks and update the documentation to reflect recent information on the current release/s.
- Familiarize: I first started exploring the Spyder IDE’s Editor pane and its features from a user perspective through existing documentation, which helped me better understand the project tasks and have clear insights into any specific needs or gaps in the live documentation.
- Write: based on the knowledge I acquired via exploration, I started updating the existing content, adding new sections and static images; while taking into consideration any feedback provided by community members or mentors.
- Demonstrate: lastly, I used the revamped Editor docs as a reference to create Gifs to illustrate written documentation on how to perform certain tasks.
The good, the bad, and the ugly!
My working experience with the Spyder community has been pleasant and fulfilling most of the time. However, some coincidental events affected my progress and made following my plan hard at times and delivering on time even harder. I am sharing some of the good and not so good lessons that I’ve learned while working on this project.
- Go with the flow; plans don’t always work out our way
- Coding is not the only valuable contribution that one can contribute to open-source
- Using or contributing to a software always starts with reading documentation
- It takes a team to create good and helpful user documentation
- Be open to work with different people, and expect to learn more from those with difficult attitude
- Even during times of disagreement; still be KIND!
- Remember, "Editing is done to communicate meaning" Donald Murray - Write to Learn
Finally, I hope my work on the Editor's documentation offers a better user experience, clearer structure, and an up-to-date information; encouraging users to explore Spyder deeper, and—eventually—reducing questions and issues related to the Editor pane.
You can browse the new and updated Editor's documentation HERE.