Linting For Non-Inclusive Language

Last week we went over linting for non-inclusive language. During class, I was confronted with the idea that certain phrasing that I often use could be taken negatively. My last blog was about the best practices for software documentation. The blog I found mentioned inclusive language briefly at the end and didn’t go into much detail. Because of this, I decided to find a blog that focuses on how to write inclusive documentation.

The blog I found that went through this topic is “How to write inclusive documentation?” by Selvaraaju Murugesan. In this article, Murugesan breaks down how to produce inclusive documentation in five steps: (1) Use gender-neutral terms, (2) Choose a neutral and friendly tone, (3) Avoid using slang words, (4) Use visuals that are diverse in nature, and (5) Use the right terms when discussing accessibility and disability. The directions and reasons behind each recommendation were clearly explained with examples to aid in understanding.

Because writers do not know anything about their audience there are many cautionary steps that a technical writer has to take.  In the new day and age, writers should keep in mind to write in a gender-neutral way to avoid discriminating against women and people of the LQBT+. He also advised using wording that removes cultural bias. He steers clear of terms like “slave-master architecture” as well. He also mentioned that local slang words may be offensive so it’s best to avoid using them. Terms that can be considered judgemental, patronizing, or exhibit euphemisms should be avoided as well. 

As alluded to in my previous blog, I have experience checking for non-inclusive language because I worked on code for Libre Food Pantry and Thea’s Pantry. When working on the linters for these projects, I discovered that there was a linter that checks for non-inclusive language. I didn’t give too much thought about the changes that the linter suggested. It wasn’t until recently in class that I gave it more thought. I didn’t think about why using “simply”, “clearly, or “of course” could be an issue for the audience. It is important to avoid deterring others from using software or wanting to be involved in the tech field. I realized that it is important to recognize that not everyone will find something simple to implement so to imply that it will be is not the best choice when trying to be inclusive. 

After going through the class activity and reading the blog, I have gained a better insight into how to choose my phrasing carefully. Although it may be slightly difficult to break certain habits, I am now better suited to identify non-inclusive language and will apply my knowledge to future projects.

Best Practices For Software Documentation

For this week’s blog, I decided to research a bit about documentation standards. I recall working on a lot of documentation for a project in the summer so I wanted to find any blogs that can help me write better documentation. The blog that I found to be particularly helpful is “Software Documentation Best Practices” by David Oragui. In his blog he touches on what software documentation is, types of software documentation, the benefits of creating it, and how to write effective documentation.

Software documentation provides information about software products and systems. The several categories and types will depend on the audience and intended use of the software. The types of software documentation that were discussed were those for end users, developers, as well as system administrators, and other IT professionals. The documentation for end users provides step-by-step instructions for common tasks and describes the features and capabilities of the software. The documentation for developers and other technical stakeholders provides technical information about the software like its API, data structures, or algorithms. The documentation for system administrators and other IT professionals includes installation guides. The breakdown of what each audience would need is very helpful to gain a deeper understanding of the topic. 

The section that explained the benefits of creating software documentation aided in my understanding of its importance. The benefits that were mentioned are improved user experience, enhanced collaboration, increased efficiency, and improved quality. Improved user experience is an obvious benefit but I didn’t think about the other benefits that were mentioned. Now that I’ve read the blog, I understand how it makes the development process consistent and helps developers work more efficiently because the necessary information is easily accessible.

I also found the section about writing effective software documentation extremely helpful. The tips that were included are: (1) Prioritize Documentation in the Development Process, (2) Identify Your Target Audience,  (3) Define the Scope and Goals, (4) Develop a Content Strategy, (5) Create a Style Guide, (6) Write Clearly and Concisely, and (7) Review and Revise. The additional best practices that he included at the end were extremely useful as well. The tips for including examples and exercises, using a consistent structure and format, and ensuring inclusivity and accessibility are very important. I found many of the tips to be familiar. While working on software in the summer, the team I was working with made sure to follow a style guide and include examples. After we split up to write the documentation for different tools, we made sure to have another set of eyes for review. We also used tools to detect gendered and biased language.

Although I am somewhat familiar with software documentation best practices, reading through useful information on the topic helped solidify what I already knew and provided me with new knowledge to put into practice. 

Understanding Software Licensing

The article I chose for this week’s blog is “Understanding Software Licensing”. This blog discusses what a software license is, how it works, why it matters, a few types of software licenses, and how to decide the best type of license for your software. In class, we discussed the topics that were brought up in this blog so I decided to do a deeper dive into software licenses to refresh my mind on the information that we reviewed and possibly gain a better understanding of it. 

The author tackles the topic in an organized manner that makes each part easy to follow. In the section about why software licenses matter, the author outlines clear advantages from different standpoints. For example, he states that from a developer standpoint, they offer benefits like “preventing users from performing actions like copying and distributing your software, if the license prohibits it, limiting your own liability, spelling out your own rights as a developer, and allowing you to control the usage of your product”. He then outlines the benefits from a user’s standpoint; he mentions that it helps you manage your tools and resources,  prevents you from paying for tools that aren’t necessary for your business, and clarifies how the provider can use your private information. The choice to clearly outline the advantages from each standpoint aids in the reader’s understanding of the importance of licensing software.

The sections on the types of licenses were beneficial. The public domain license is a simple license to understand. The section that defines a copyleft license is an open-source license meaning that deviation of the code must have the same terms. Defining the GNU license as a weak copyleft license helped to simplify what it was. His explanation of a permissive license was helpful as well. He defined each type of license with a short, simple statement at the beginning and then went on to further explain them.

The other part of the article that I found to be very helpful is the section about how to figure out what the best type of license is for your software. Because software licensing is new to me, I was struggling to pick which license I should use for a project. The author mentions that you should “consider the different models, thinking about the purpose behind your code and what you want users to be able — and not be able — to do with it”. It can be very challenging to outline the true purpose of your code clearly. It was very helpful that the author clearly defined the types of licenses in simple terms and then gave simple advice on how to pick which one to use. I enjoyed reading this blog and will use the knowledge for my future projects.

What Makes a Daily Scrum Effective?

This week in class we discussed the process of scrum. Scrum is an agile framework that can be applied to any project or product development effort. It promotes flexibility by encouraging openness, inspection, and adaptation. This loose framework allows teams to adopt it and make changes that benefit their team’s workflow. Unlike the waterfall development approach, where each step must be completed before moving to the next, a scrum team works in small increments over a smaller period. That period consist of the sprint, sprint planning, daily scrum, sprint review, and the sprint retrospective. The scrum event that piqued my interest after reviewing it in class was the daily scrum.

The blog, “Ten Tips for More Effective Daily Scrums” by Mike Cohn,  brought up some interesting and important points. The ten points that were mentioned were: (1) talk almost exclusively about the work of the current sprint, (2) limit discussion to what was and will be accomplished, (3) talk about impediments, not “blockers”, (4) give people something to say about their work not directed toward the sprint goal, (5) give team members a way to indicate when someone is rambling, (6) have people point to what they’re working on, (7) update the sprint backlog but don’t let numbers become the focus, (8) vary how the daily scrum is conducted, (9) keep everyone guessing as to who will speak next and (10) make it painful to ramble too long. 

During the summer, I had the chance to work on software for our university. It was my first time experiencing the scrum workflow. Our team implemented some of these tips during our daily meetings, mainly points 1, 2, 3, and 6 so it was interesting to hear the author’s perspective on what other methods make a daily standup more effective. The points that cater towards diminishing rambling were a fascinating read. While discussing methods to indicate when a member is rambling, examples of using buzzers, holding up rubber hats, and using dolls were mentioned. Although strange to me, those methods show that different teams use what’s best for them. Cohn’s ninth point about keeping everyone guessing as to who will speak next discussed more methods to make the meeting fun to help avoid tuning other members out while they are speaking. While working on software in the summer, I didn’t think about fun ways to improve daily scrum because it was all so new to me. It makes sense to implement something to make the meeting more engaging because, like he said, I did find myself zoning out at times. 

Because I have such little experience with a scrum team, I enjoyed reading about possible ways to improve a team’s process .It helped me realize just how different another team’s methods could be and what I could possibly implement in the future.

Hello Hello~~

I have to say…the software development path is a little fun. This blog is meant to track my journey as I learn how to be a successful software engineer. I started my tech journey by taking an IT class in my junior year of high school and now I’m a junior studying Computer Science at my university. We all start somewhere. I’m now in a software process management class so lets see how this goes.