I’m writing about this first because this does a good job of summarizing the work that needed to happen and what my plan was but it was written after part 0 was completed.
The original idea of creating a Software Design Document for this project didn’t come from the technical requirements of the project but from watching this video. The project’s intent was to simulate a professional backend software project and so I felt adding a design document would also be a great experience.
The main goal of the Software Design Document was to share my idea for the design of the system and give people the opportunity to critique the design and give their opinions. As someone who is an advanced beginner in backend dev work, the critiques would be just as valuable as the experience of completing the project. I get to engage with more experienced engineers, I get to learn about techniques I hadn’t come across before and, in the spirit of the project, I get to simulate the experience of being a Back-End Engineer architecting a system and having to defend and/or update my design based on my fellow colleague’s feedback.
With that in mind, I went to work on writing the document.
The unique challenge of writing the document was actually the fact that its intention was to portray a system whose design was in question and potentially fluid, despite that not being the case at all. One of the main reasons for this was because there is a requirement for the project I was doing to include my design decisions as a document and so I purposely made the design document to represent the architecture as if it were in the future and then the design decisions document would be me justifying what I did. I included a reflections section in the document but it’s mostly on how the project went rather than focusing on technical details.
Writing the document took me about 3 days to complete and once completed, I quickly passed it around to get opinions on it. It was mostly received positively with not too many negative critiques on the architecture. Multiple people reached out to say that they liked the way the code was structured and easy to read which is something I really appreciated since I put a lot of effort in doing that. One critique which I got a few times was how I structured the API endpoints. People would often say that they were more used to seeing ‘resourceful’ endpoints. This brought up an interesting discussion about the benefits of structuring endpoints like that and I am seriously considering redesigning the endpoints in this manner for the next iteration of the project which would be reflected in the next design document.
While my main intention was to get feedback on the architecture of the system itself, I also got a fair amount of feedback on how to articulate myself through the document. One particular thing that really resonated with me (I purposefully try to code for this as well) is to write the document so that any level Engineer can read it. If a junior Engineer were to pick up this document and start reading it, they should be able to understand the discussion or be given the tools to understand the discussion that was going on. An example of this is talking about openAPI and Swagger in the document. Just a quick link to Swagger.io where they talk about what it is goes a long way in helping someone understand what is being talked about if they didn’t know in the first place.
I felt writing the document was a great success! I learned so much from everyone’s critiques of it and I found more people were willing to actually look over the document than the code I had written. I also asked people to critique the project but very rarely had I gotten feedback on it despite regularly asking for it. I feel because it made the whole thing easier to digest and understand, people were more willing to give their opinion. I look forward to writing the next design document for the next part of the project.
If you’re interested in reading it, the design document can be found here.
In the next article of this series, I’ll talk about writing the Swagger spec to satisfy one of the project’s technical requirements.
Top comments (0)