Through my past couple blogs of Object Oriented Programming, REST APIs, and frameworks, I often came across the word “documentation” but commonly overthought it and didn’t do any more investigating into it. With that being said, I came across this blog 9 Software Documentation Best Practices + Real Examples and I feel a lot more comfortable with documentation as a whole. https://www.atlassian.com/blog/loom/software-documentation-best-practices

Imagine, you and your developing team are coding away on an application, but then an error appears, by which no one present knows how to solve it.

To solve this error, your options are:

1. Slack threads
2. Stack Overflow
3. Emails back and fourth 
4. Documentation 

The most promising answer of these options are documentation. With great documentation, you will get a clear precise solution to the problem you are facing. 

Now, what exactly is documentation? Documentation is written information that clearly explains the program’s structure, functionality, and when/how to use it; should be used as a guide or as a reference pointer for developers. If the documentation is done right, it reduces friction, boosts productivity, and helps the user understand the code from all angles due to the information of processes, functionalities, and solutions.

With so many benefits, documentation should be at the forefront of software developing teams, but unfortunately, it often gets overlooked. One of the main reasons for this is because documentation can go outdated very quickly. 

That being stated, here are nine ways to make sure your documentation will always be great:

1. Know your target audience
   1. General Audience (surface level) vs Developers (technical)
2. Keep it user-friendly
   1. Having a table of contents with clear headings can make it a lot more easier to find what the user is looking for
3. Use version control
   1. By doing this, you will be able to see all the latest updates
4. Incorporate visuals
   1. Some people are visual learners, who work better off of a video, photo and/or diagram (within reason)
5. Adopt a documentation style guide
   1. Consistent styling will make it easier for the user when going through each documentation type from said releasers (writers/developers)
6. Update regularly
   1. By doing this, your documentation will align with the latest software functionality
7. Encourage collaborative documentation
   1. Working together in person or remotely 
   2. Always good to have a peer’s input
8. Provide troubleshooting and FAQs
   1. This enables users to find solutions for common issues very effectively
9. Use documentation templates
   1. This will give a great start to all coming contributors of the documentation 

Overall, I really enjoyed this article and its purpose of making software documentation better. Furthermore, it mentioned how Google and Microsoft all stick to the same consistent documentation perspectively, which opened my eyes of how important consistency is in documentation within a company. Along with this, before “jumping” into something new, it will definitely be worth it to go over the documentation. Understanding and referencing any documentation is a skill.

From the blog CS@Worcester – Programming with Santiago by Santiago Donadio and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.