Update GNOME Applications Help Documentation (Update App help)
Technical Writer – Pranali Deshmukh
Project Mentor – Shaun McCance
Important Links
- My Website
- GitLab Profile
- Link of my CV
- Link of my GSoD Proposal
- My Blog Posts about GSoD
- My Contributions List
Project description
Review and update the help documentation for a number of GNOME applications as tracked in https://wiki.gnome.org/DocumentationProject/Tasks/ApplicationHelp.
Even though GNOME is extremely user-friendly, it is a large and complex system, and thus, requires some learning to use to the fullest and to do so GNOME has provided some very useful documentation. This project proposed a review and updation of a number GNOME application Help documents. The status of these documents are tracked in the Application Help Wiki (https://wiki.gnome.org/DocumentationProject/Tasks/ApplicationHelp).
Issues I contributed to:
Update help docs for 3.38
Find and implement changes to the user help docs for Boxes to ensure that the documents are in sync with version 3.38
- Update the Create Box Page
- Remove the Share Clipboard option
- Update the User Interface page
- Remove the Share Clipboard switch reference from the General tab section
- Add an entry about the 3D Acceleration switch to the General tab section
- Create new pages for the following new features:
- 3D acceleration
- Identify an OS
- Edit VM configuration/XML
Update help docs for 3.38
Find and implement changes to the user help docs for the calculator to ensure that the documents are in sync with version 3.38
- Update the following help pages:
- Update Superscript and Subscript
- Update Using the Keyboard
- Update Using the history view
- We don’t appear to have a page explaining the modes. We should add one of those and link to it everywhere we mention a mode. Create new pages for the following features:
- Modes Overview
- Basic Mode
- Advanced Mode
- Financial Mode
- Programming Mode
- Keyboard Mode
Update help docs for 3.38
Find and implement changes to the user help docs for the GNOME Contacts app to ensure that the documents are in sync with version 3.38
Update the following help pages:
- Update Contact add and remove
- Update Starting Contacts for the first time
- Update Connect with your contact
- Update Edit contact details
Help: missing word in gedit-open-recent.page
In https://gitlab.gnome.org/GNOME/gedit/-/blob/master/help/C/gedit-open-recent.page is a string that starts with When hovering with the mouse a recently-used file from the menu, the full path to the file is displayed
here my guess is that the word over is missing, so that it really should start with When hovering with the mouse over a recently-used file
help: Zealous animation option mixed up
In https://gitlab.gnome.org/GNOME/swell-foop/-/blob/master/help/C/preferences.page is the string
To slow down the animations, uncheck the checkbox.
This feels wrong, as disabling the more advanced graphics probably would increase the speed. Should this be check the <gui style=\"checkbox\">Zealous Animation</gui> checkbox instead?
Furthermore the string before that is:
If it is too fast for you and you would like playing slower then this may be too fast for you.
The end of this string is always true if the start is, and it repeats itself, so it might be nice to change it a bit. Maybe shortening it to something like If it is too fast for you, then you might like playing slower.
archive-edit.page: Add F2 key shortcut.
https://gitlab.gnome.org/GNOME/file-roller/-/blob/master/help/C/archive-edit.page#L48
<p>Right-click on the file and choose <gui style="menuitem">Rename…</gui>.
My suggestion:
<p>Right-click on the file and choose <gui style="menuitem">Rename…</gui> or press <key>F2</key>
format-list.page in manual needs to be revised.
Link to original bug (#766195)
Description
While reading help/C/format-list.page however I noticed that the “Bullets” button has been moved to a popover, so this page needs to be revised as agreed in bug 766129.
Consolidate the many Printing related pages in Evince user help
Those gazillions of pages are hard to maintain and unneededly cumbersome. Plus:
- print-order.page and its image seem to be just copied from https://gitlab.gnome.org/GNOME/gnome-user-docs/blob/master/gnome-help/C/printing-select.page but not kept in sync
- print-select.page and its image seem to be copied from https://gitlab.gnome.org/GNOME/gnome-user-docs/blob/master/gnome-help/C/printing-order.page but not kept in sync
Both could be a simple <p>Please see <link xref="help:gnome-help/printing-*****" href="https://help.gnome.org/users/gnome-help/stable/printing-*****">the GNOME Desktop Help</link>.</p> but maybe we had standalone Windows users in mind here?
My Contributions:
Summary of the current state of the project
Currently, core projects like Boxes, Calculator and Contacts have been updated to GNOME 3.38 which was the target version of GNOME for the scope of GSoD. While most of the Merge Requests have been merged, some are still under review.
Along with that I am going to continue my work on updating documents for GNOME and my next task is updating Evince.
Challenges:
- The very first challenge was Applying for GSoD, choosing the project and preparing the proposal.
- Learning Open Source project workflows and Technical Writing tools
- Finding potential issues and working with developers to make sure that the App Help Documentation is complete, easy to access and easy to understand.
- Understanding the existing documentation and creating new documentation from scratch.
Key Learnings:
- Finding issues in existing documentation and creating Issues on Upstream of GitLab so others also can work on it and I will summarize my work under one issue.
- How open source communities collaborate with each other remotely using communication Channels like IRC, BluJeans, Manage work through Version Control systems like GitLab which allows software projects to keep track of all versions and revert to previous versions if necessary.
- Working as a technical writer for GNOME helped me to learn Technical writing tools like Mallard along with that I got to test applications like Boxes, Contacts and Calculator in detail, it also had a chance to Install Fedora 32 and 33 on my system which was a great learning experience.
- With GSoD I not only learned Technical writing but also learned blog writing skills too.
Plans after GSoD
GNOME User documentation for Core projects are up-to-date but there are other tasks which needs to be completed and I would love to continue my work with GNOME after GSoD as well along with that as I like what I am doing under GNOME and I noticed my university is not much involved with Open Source that much and students in my class were have very little understanding of Open Source I decided to continue my work with GNOME and take that as my final year project so I can write a paper about Open Source details from my experience. Which provided me with a chance to continue what I love to do in open source alongside my university while sharing my knowledge with others.
Pranali Deshmukh 
2 thoughts on “GSoD Project Report”