Week 9 (9th Nov – 22nd Nov, 2020)
This week was mostly all about finishing a task that I had taken up earlier during the last couple of weeks, which was about GNOME Calculator’s Operational modes. So, this week, I thought that rather than taking on a completely new task I should finish this one first as it was due for quite some time now.
The idea here was to consolidate all documentation regarding the different operational modes of the calculator into a single section consisting of an overview page along with dedicated pages for each of the operational modes: Basic, Advanced, Financial, Programming and Keyboard modes.
I started working on this a few weeks back and spent quite some time on it however, I didn’t manage to finish it yet. There were quite a few reasons behind this including the fact that it required me to do a surprisingly huge amount of research work. Honestly speaking, some of the functionalities available within a few modes like the Financial and Programming modes involved quite a few mathematical concepts that I was quite new to and and none to very little knowledge about.
The first thing that I did in this regard was to create a plan of tackling this work as it involved a considerable amount of changes. The plan that I had in my mind was that I would first create a new overview page with an introduction to each of the different operational modes within it and to link it up with the existing pages. Refactor the existing pages on the programming and financial modes. And finally create a new section on the index page for Operational Modes under which to consolidate all the documents. Once this was done I could next move onto creating new documents about the Basic, Advanced and Keyboard modes.
Sounds simple right? What could be so difficult about it, I thought! If only I knew!!!!
As soon as I started working on this, it soon felt like I had opened up Pandora’s box itself! I couldn’t believe the amount of time and effort that I ended up spending behind just the initial part of the job, i.e. refactoring the existing pages, creating a new section, consolidating the pages under this section and creating an overview page.
It wasn’t the technical part of writing or refactoring the docs that was challenging, but rather the job of finding and deciding upon the correct vocabulary for each and every sentence in each of the documents. This became especially evident after I opened the MR for this first set of change. I immediately got a huge number of change suggestions for it. Everything from the page description to the use of screenshots came under the scanner. (psst… the MR is still under active review and I’m still implementing review suggestions! 😅).
I must admit that this MR has the longest list of change suggestions of all my MRs till date, and frankly, it’s turning out to be a great learning opportunity for me so far. I am getting to learn a lot about things like language conventions for page descriptions to the overall layout of a help document in general. As an example, one of the things that was quite an important learning for me here was the fact that including screenshots of an application within a help document for that application might not always be quite as productive. Since the user that would anyway be accessing the help docs for a certain mode would have at least seen the UI of that particular mode of the application when they invoke it in the first place itself.
Overall, it’s been quite a fun week in terms of learning so far, and hopefully I would soon be able to close the loop on this particular set of work on GNOME Calculator! 🤞
Ciao! See you next week! 😊 👋