Communication with those who help construct it or those who will use it is an essential component of any project. Software documentation serves both these ends, as it informs anyone approaching the project of topics such as the requirements used to run said software, instructions, and myriad other facets of the project. Documentation is created for those interested in the specified software/project. The Swimm Team, in their article What is Software Documentation? Types, tools, and best practices, list two types of documentation. These are external and internal documentation.

External documentation seeks to explain all aspects of the software that are not locally accessed. Most of this documentation involves user interaction. This is seen through End-User documentation, which provides the user with instructions on using the software, or through Just-In-Time Documentation, which guides the user while the program executes. A more technical piece of documentation, API documentation, is also considered external. Although most users may not directly interact with the API, this type of documentation is targeted towards developers who may want to expand the API functionality or use it in their projects. Due to the accessibility of external functions, its documentation must be equally accessible to its audience. A level of abstraction must be provided to reach this goal, as uninformed users do not need to understand how the internal systems of the software function, but rather they must learn how to interact with it.

Internal documentation refers to everything ‘behind the scenes’ so to speak. Contrary to external documentation, this documentation is less accessible, meaning it can go into detail on how the systems of the specified software work. Due to this complexity, it serves as a great introduction to the project and can be used to onboard new developers. Internal documentation ranges from information regarding the development cycle of the software, as seen through scheduling documentation,  to design choices seen throughout, which can be found in Software design documents. During the development process, software engineers can refer to internal documentation to ensure their contributions follow the team’s vision for the software.

My experience with software documentation has been limited up until this year. My most recent experience with documentation was through the HFOSS project Theas’ Pantry. Within this project, there was API documentation, available through a .yaml file, which listed all functions and associated code with all API calls. Additionally, there was indirect documentation offered through activities introducing onboarding developers onto the project. Each of these activities introduced a broad topic, such as software architecture, which then transitioned into how it’s applied to Theas’ Pantry. This untraditional form of documentation allows the onboarding developer to interact with the components in a microcosm before they apply their knowledge on the project. Documentation is a vital component of software development. Without supporting texts such as this, clients interested in the project would be met with inaccessibility, and onboarding (in addition to current) developers may not understand the project as a whole which could jeopardize the production of such. 

Link to Article:

https://swimm.io/learn/software-documentation/what-is-software-documentation-types-tools-and-best-practices

-AG

From the blog CS@Worcester – Computer Science Progression by ageorge4756 and used with permission of the author. All other rights reserved by the author.

I chose the blog post, “Software Documentation Best Practices” by David Oragui because it addresses the challenges in documentation and how to go about following the best practices. The blog shows us all of the best practices of documenting your work to prevent having challenges when faced with the task. In my time coding, documenting has been a struggle knowing how to document and when to do it. This is what led me to choose this blog post, so I can learn how to not make these mistakes in the future and become better when it comes to creating documentation.

The blog explained to the reader how software documentation is essential for enhancing user experience and ensuring consistent software development. Despite its benefits, developers often neglect documentation due to constraints like time, expertise, or resources. This gap can result in user difficulties and inefficiencies in development processes. The blog first described the  types of software documentation. First, project documentation which is aimed at development teams, covering technical design, project plans, and requirements. Next is product documentation, this is more user-focused, including instructional manuals, reference guides, and installation instructions. Third, the blog described process documentation which details steps for development, testing, and maintenance, ensuring consistency and clarity. Then, technical documentation which provides in-depth technical insights, such as APIs, architecture, and data models. In addition, there is system documentation which explains system architecture, components, and troubleshooting methods. Last is user documentation, this is similar to product documentation as it is user-friendly materials like how-to guides, tutorials, and reference docs. The benefits of documentation include improved user experience, enhanced collaboration, increased efficiency and improved quality. The best practices for writing documentation include prioritizing documentation, identifying the target audience, defining the scope, developing a strategy and being able to write clearly for the audience.

From the blog, I was able to rethink my use of documentation and highlighted the best practice when creating documentation. Going forward, I plan to be more thoughtful about my use of documentation and how I go about creating it. The blog taught me that well-designed documentation should cover all the necessary information to allow others to understand without being confusing.. This perspective will help me develop documentation that is easily readable and documents what work is being created. After reading, I feel like I will be able to not make as many mistakes when it comes to creating documentation.

https://helpjuice.com/blog/software-documentation

From the blog CS@Worcester – Giovanni Casiano – Software Development by Giovanni Casiano and used with permission of the author. All other rights reserved by the author.

Week-13: 12/2/2024

This week in class we worked on merge conflicts and how to resolve them. I had to do an activity that had to do with solving a merge conflict. This experience was not as frustrating as I thought it was going to be. While doing the activity, Professor Wurst highlighted how important it is to understand version control systems like Git and to develop effective strategies for resolving conflicts collaboratively.

On this week’s blog hunt, I came across a helpful blog post by Sid Puri titled “Git Merge Conflicts,” which provided a clear explanation of what merge conflicts are, why they occur, and how to resolve them using Git tools. It broke down the process into manageable steps and even offered advice on how to prevent these conflicts from happening in the first place.

One of the key takeaways for me was understanding the root cause of merge conflicts: multiple developers making changes to the same file at the same time. Because Git can’t automatically figure out which changes to keep, it flags these conflicts and requires manual intervention. The post explained how to use Git’s notification system to identify conflicts and then how to manually merge code using conflict markers – those weird symbols like <<<<<<<, =======, and >>>>>>> that used to make my head spin.

The post also emphasized the importance of communication in preventing merge conflicts. This really resonated with me because our team conflict stemmed from two of us accidentally modifying the same section of code. If we had just communicated about our tasks beforehand, we could have avoided the whole issue. Moving forward, I’m definitely going to advocate for more frequent team check-ins and a more organized approach to task allocation.

What I really appreciated about the blog post was its practical approach to conflict resolution. It explained how to use built-in Git tools like git status and git diff to navigate conflicts with confidence. Mastering these tools will definitely save me time and frustration in future projects. Plus, learning how to handle and resolve conflicts collaboratively is a transferable skill that will be valuable in any team setting, not just software development.

Overall, this blog post was a great resource that directly complemented our coursework on team-based software development. It reinforced the idea that understanding and resolving merge conflicts isn’t just a technical skill; it’s an essential component of effective teamwork in software engineering. I feel much more prepared to tackle these challenges in the future and to contribute more effectively to my team projects.

Blog link: https://medium.com/version-control-system/git-merge-conflicts-4a18073dcc96

From the blog CS@Worcester – computingDiaries by hndaie and used with permission of the author. All other rights reserved by the author.

Week-13: 12/2/2024

Understanding software architectural patterns is critical in the software development industry for creating strong, scalable, and maintainable products.

A recent Turing blog post, “Software Architecture Patterns and Types,” has been useful in solidifying my understanding of this important concept. This article provided a comprehensive overview of various patterns, including monolithic, microservices, event-driven, layered, and serverless architectures. The article clearly gives explanations of each pattern’s design principles, advantages, and limitations.

For instance, while monolithic architectures offer simplicity, they often struggle with scalability. On the other hand, microservices excel in scalability and allow for independent deployment but can introduce complexity in maintenance and debugging. The article also explores emerging trends like serverless architecture, emphasizing their importance in modern cloud-based systems.

The practical examples and concise explanations in the article made it extremely relevant to what I learned in my classes, particularly my software construction, design, & architecture class. The discussion on system scalability and maintainability directly aligns with the topics we’re covering.

One of the most valuable takeaways for me was the emphasis on aligning architectural decisions with business objectives. The article effectively illustrates that a microservices architecture, while attractive for its scalability, might be overkill for a small-scale project. This resonated strongly with my recent experience in a group project where we debated between microservices and a layered design. Reflecting on the deployment and dependency management challenges we faced, the article validated our decision to opt for a simpler layered design as a better fit for our project’s scope.

Furthermore, the article’s discussion of serverless architecture was truly eye-opening. I had previously held a somewhat simplistic view of serverless as a universal scaling solution. However, the article shed light on its potential drawbacks, such as vendor lock-in and latency issues. This more nuanced perspective will undoubtedly inform my approach to future projects, encouraging me to critically evaluate new trends before jumping on the bandwagon.

Moving forward, I intend to apply this knowledge by diligently assessing the specific needs and constraints of each project before selecting an architectural pattern. For instance, when tackling a high-traffic e-commerce site, I would now consider employing an event-driven architecture to effectively handle asynchronous data flow. Alternatively, for smaller projects, I would advocate for a monolithic or layered approach to minimize overhead.

By understanding the trade-offs inherent in different architectural patterns, I feel better prepared to design and build software systems that are not only functional but also scalable, maintainable, and aligned with business goals.

Blog link: https://www.turing.com/blog/software-architecture-patterns-types

From the blog CS@Worcester – computingDiaries by hndaie and used with permission of the author. All other rights reserved by the author.

This week, I explored the blog post “Mastering Reagent: Finding the Balance Between Readability and Performance” on Clean Coders. This post delves into the challenges of balancing readability and performance when using Reagent, a ClojureScript library for building user interfaces. It highlights techniques to maintain code clarity while optimizing performance, especially in interactive web applications.

The author discusses common pitfalls, such as overusing lifecycle methods, creating unnecessary computations, and mishandling state updates, all of which can lead to unresponsive or hard-to-maintain code. The blog suggests best practices, including leveraging idiomatic ClojureScript constructs and modularizing components to enhance both readability and runtime efficiency. Practical examples include minimizing expensive computations by using reagent.core/track and ensuring that components don’t re-render unnecessarily with reagent.core/shouldComponentUpdate. The author also emphasizes that while performance is crucial, readability often has a long-term payoff, especially in collaborative environments where maintainable code saves time.

I chose this blog post because our course has emphasized the importance of clean, maintainable code in software development and maintenance. These lessons have led us to balance the trade-offs between performance and code clarity, and understanding how to achieve that in application is very important. Additionally, we’ve explored a lot of similar clean code attributes in class that are expanded on within this post and tied to the context of UI frameworks.

What stood out to me most was the emphasis on maintaining readability without compromising performance, a principle applicable across programming domains. For instance, I’ve sometimes been tempted to optimize prematurely, leading to messy code that became hard to debug or modify later. This post reinforced the idea that readable code doesn’t just benefit the developer in the moment but also improves team productivity and ensures the application can be scaled or updated more easily in the future.

One of the key takeaways for me was the use of tools like track to manage expensive computations efficiently. I had not considered how reactivity frameworks like Reagent allow for targeted optimizations without sacrificing clarity. Moving forward, I plan to apply this principle in my projects by carefully identifying bottlenecks and ensuring that optimizations are implemented only where they provide tangible benefits.

This material has given me a new perspective on how to approach UI development. While I’ve worked primarily with simpler frameworks, I now see how the same balance between readability and performance applies universally. Whether I’m working with Reagent, React, or any other tool, the insights from this post will help guide my decision-making and ensure I focus on long-term maintainability as well as immediate efficiency.

Overall, this blog post offers practical advice for developers working with Reagent or similar UI libraries. I highly recommend reading it for anyone interested in crafting user interfaces that are both efficient and easy to maintain. The post can be found here: “Mastering Reagent: Finding the Balance Between Readability and Performance.”

From the blog CS@Worcester – CS Journal by Alivia Glynn and used with permission of the author. All other rights reserved by the author.

Hello, and today’s blog post is about Scrum. For those of you who do not know, Scrum is basically a way to work as a team efficiently and effectively. I am glad that Professor Wurst chose to expose us to Scrum in his curriculum this semester because this method of teamwork is very interesting, and it actually seems like it could be useful to me in the future. The thing I really like about Scrum is that it is INCREDIBLY organized. Each day is planned out to an hour, and I think that having a schedule that is organized and efficient is very important when you actually want to get work done. Planning out your schedule/agenda ahead of time ensures that everyone on the team stays on track with minimal distractions. This method also is all about improvement. There are reflections/retrospectives at the end of every sprint (which is pretty much another way to say “project”). We went over this in detail during our class time, which engraved a lot of the Scrum knowledge in our heads. We also took official quizzes which helped us become “certified.” I think taking these Scrum tests were beneficial because we had to reach a certain score, and if we didn’t get it, we would have to re-do the tests until we had a much better understanding of the concepts.

Scrum uses the Agile framework, which I talked more about in one of my previous blogs. Scrum is based off of three pillars: transparency, inspection, and adaptation. The official Scrum website described the process of working using Scrum as “working through small experiments, learning from that work and adapting both what you are doing and how you are doing it as needed.” Scrum also has important values: courage, focus, commitment, respect, and openness. These values are each crucial to making this process work.

The article I chose to help me explain Scrum for this blog is linked here: An Introduction to Scrum | Lucidspark

This article describes Scrum as “an iterative, adaptable approach to software development.” It talks about how most software development methodologies are very linear, meaning there is not much room for improvement. Scrum on the other hand, as I mentioned before, follows the Agile approach rather than the Waterfall methodology, which makes for great adaptability. The article also re-iterates how Scrum is all about teamwork and collaboration. It goes into detail about each role in the Scrum team, and what all the events are in the sprints. I think this article is worth a read, and it is supposed to be just an 8-minute read as well.

Overall, Scrum is definitely one of the best software development methodologies that are in sync with Agile ideologies, so I am glad that we learnt about it!

From the blog cs@worcester – Akshay&#039;s Blog by Akshay Ganesh and used with permission of the author. All other rights reserved by the author.

This week’s post will cover REST APIs, Representational State Transfer Application Programming Interfaces. One of the main key principles of RESTful APIs is the seperation between the frontend UI the user interacts with and the backend server. Postman’s blog highlights this as, “The client’s domain concerns UI and request-gathering, while the server’s domain concerns focus on data access, workload management, and security”. The primary purpose of REST APIs is to allow different software systems to interact and exchange data over the web. REST mainly focuses on stateless communication, where each request from a client contains all the information needed for the server to process it.

REST APIs use HTTP methods and standard URL structures to enable communication between clients and servers. HTTP methods play an essential role in REST APIs. These methods correspond to CRUD (Create, Read, Update, Delete) operations in software. The POST method is used to create, while GET retrieves data from the server. PUT and PATCH are used to update existing data, with PUT replacing the entire resource and PATCH modifying specific parts. DELETE removes data. In addition, REST APIs use status codes to indicate the outcome of an operation, For example, a 200 status code indicates a successful operation, 201 signifies resource creation, 404 means a resource was not found, and 500 represents a server error. Including appropriate status codes in API responses helps clients understand the results of their requests and handle errors effectively.

The blog post I researched by Postman highlights how REST is widely used across various industries. For example, e-commerce platforms use REST APIs to manage product information and process orders. Social media applications utilize REST APIs to handle user profiles and posts. Cloud services often provide REST APIs to allow developers to interact with their resources programmatically. The blog also mentions another type of API called SOAP, standing for Simple Object Access Project. SOAP is considered a protocol, while REST is considered a set of guidelines. Unlike REST which uses methods like JSON, URLs, and HTTP, SOAP uses XML for sending data. One of the main reasons why SOAP might be preferred over the more popular REST is because SOAP supports WS-Security, which provides a framework for securing messages, including encryption, digital signatures, and authentication. This makes SOAP more suitable for applications handling sensitive data. Corporations like banks and hospitals dealing with sensitive user information could utilize to prevent information breaches.

These APIs provide a consistent way for systems to interact and exchange data while adhering to a set of well-defined principles. By understanding HTTP methods, status codes, and data formats, developers can create APIs that users can understand and use.

Blog: https://blog.postman.com/rest-api-examples/

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