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. 

From the blog CS@Worcester – Live Laugh Code by Shamarah Ramirez and used with permission of the author. All other rights reserved by the author.

This podcast by All The Code discusses the use of GitHub and GitLab APIs for managing software development projects. The host of the podcast conveyed his disdain for GitHub’s API when he was involved in a project that utilized GitHub to share images and video links. Users had to request access to the repository in order to access the content, which the speaker did not like. He emphasized that requesting access on GitHub isn’t user friendly to someone who isn’t experienced with the site. When the hosts talked about GitLab, they described the platform as “amazing” and its ability to do “wonderful stuff”. Additionally, The speakers compared both GitHub and GitLab’s documentation and found GitLab to be the all around better platform documentation wise. Lastly, the podcast hosts argue that GitHub is ideal for large companies as GitLab is suited for smaller companies/teams. I chose this specific podcast because I have worked with both GitHub and GitLab in this class and can’t seem to prefer one over the other. I will say that I was more comfortable with traversing GitHub compared to GitLab. Although GitLab is considered to be easier to navigate, I often find myself struggling to access projects and repositories in different groups within GitLab. I’m hoping as time comes, I will get more comfortable with navigating the platform. This podcast has changed my view on GitLab, knowing that GitLab is more user friendly with documentation is extremely important to consider when choosing which platform to use mainly. Of course, companies will expect their teams to use the same platform to prevent any conversion issues. Having solid documentation in your software development projects is vital so new developers/users can easily understand the project and its goal. Going forward with this information, I will experiment with the various features GitLab has to offer regarding documentation. For example, GitLab has a feature called GitLab Flavored Markdown (GLFM) which gives you the ability to render certain text with a style. GitLab Flavored Markdown allows you the change the color of text, add emojis, create detailed lists, and more.

Selected Podcast: https://www.youtube.com/watch?v=LsRZiWPPiEQ&ab_channel=AllTheCode

From the blog CS@Worcester – Computer Science Through a Junior by Winston Luu and used with permission of the author. All other rights reserved by the author.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

GRASP (General Responsibility Assignment Software Patterns) assigns responsibilities for different modules of code in object-oriented software development. There are seven types of roles assigned to classes and objects to easily organize the responsibilities. These roles include Controller, Information Expert, Creator, High Cohesion, Low Coupling, Polymorphism, and Protected Classes. It is important to note that GRASP is occasionally paired with SOLID principles, making for the combination SOLID GRASP. Design patterns like this help keep code clean and more organized, making it more comprehensible and reusable.

Controller suggests that the entity responsible for handling a system operation should be its own class to act as an intermediary between the user interface and the logic of the program. This helps separate concerns as well as improve flexibility of the whole system. Information Expert focuses on assigning responsibilities to classes that include the most information required to fulfill them. By following this principle, we can design systems where responsibilities are distributed efficiently amongst classes which in turn reduces dependencies. Creator guides the allocation of responsibility for creating objects. A class should be responsible for creating objects of other classes if the first class aggregates or has a composition relationship with the second class. By following this, there will be less coupling between classes and ensures better maintainability. High cohesion advocates designing classes with a clear and focused purpose. Each class should have a single responsibility and capture related behaviors and data. This provides easier comprehension of the code and simpler test cases to write. Low Coupling relies on designing classes with minimal dependencies on other classes. The less interconnections between classes allows to create a more modular system and improves maintainability since changes to one class are less likely to affect other classes. Polymorphism enables objects of different classes to be treated the same throughout a common interface in object-oriented design. Leveraging this principle allows for the design of systems to be extensible and adaptable to new requirements and promotes loosely coupled systems.

Applying GRASP principles ensures a clear distribution of responsibilities and promotes low coupling and high cohesion among classes. These principles help create an understandable design architecture while also providing the ability to adapt to future changes. This also helps team members collaborate due to better facilitation for communication among developers and it establishes a common understanding of each component’s role and interactions.

What is GRASP (General Responsibility Assignment Software Patterns)? | Definition from TechTarget

GRASP Principles: Object-Oriented Design Patterns | by Patrick Karsh | Medium

From the blog CS@Worcester – Jason Lee Computer Science Blog by jlee3811 and used with permission of the author. All other rights reserved by the author.

So, since the end of the semester is coming up, I should be posting weekly for the near future, so stay tuned for a lot from me! With this week of work, I have two topics I wanted to discuss, both related to each class I’m taking with Professor Wurst.

Firstly, on the Software Process Management side, I wanted to discuss how we’re using Scrum, and the way it’s set up. We’re using GitLab’s issue boards, dividing them amongst where they currently are in The Sprint, with stuff like the Issue Backlog, In Process, Needs Review, Finished, and so on so forth.

This setup reminded me a hell of a lot of Trello, a website/service I’ve been using for years now! And what’s funny is that I even mentioned this in class once, and the Professor said he used to as well for Scrum. My setup is quite different compared to the setup we have on GitLab, however, it still uses a similar Scrum/Kanban-esque setup.

Here’s the two boards I mainly use, one for School, and one for Commission work, as I freelance in art. With my Comm board, it is a bit more simpler, having using tags within lists as opposed to using a list per tag. As for my schoolwork board, it’s simply just listed with each course I’m taking and items of work I need to finish. It’s a very good tool, and I highly suggest it to anyone looking to utilize Scrum or even need a good tool to organize things.

Check it out here! https://trello.com/

As for the Software Design, I was curious what kind of file the .json’s we were using were. We have been using them to store data about students and members of the modified version of LibreFoodPantry’s backend. I’ve seen them used before many times in my times modding games before, usually they store data for configuration files.

So, to learn more, I found this blog from HubSpot: https://blog.hubspot.com/website/json-files, and honestly I think I get it a bit more now. They’re simply data storage files, able to store comma seperated values, objects, and arrays. They also support multiple data types, like integer, boolean, and strings.

So putting that into the context of configuration files, like for settings in games, it makes sense why they are used, due to integer and boolean values. If an option for a game has an on/off choice, a boolean data value to hold that information would make sense, as “true” would be on, and “false” would be off. As for how integers would be used, say you want to store the value of the volume the user wants while playing the game, that can be stored as an integer from 0-100.

All in all, it’s really interesting to learn more about filetypes I don’t know too much about, and I should look into more and how they are written, like .obj, .html, and .ini.

From the blog CS@Worcester – You're Telling Me A Shrimp Wrote This Code?! by tempurashrimple and used with permission of the author. All other rights reserved by the author.