Documentation User Stories: JSDoc and Typescript
Documentation. A seemingly boring, yet extremely valuable part of any well choreographed engineering team. We prioritize documentation as a means of supporting new team members to quickly onboard and achieve consistency in our engineering work flow. One of the benefits of working with an agency of our size is our ability to balance rigor and the ability to have wiggle room when planning and delivering technical work. The unique needs of each client project are what guides our application of sound engineering habits.
Perry Von Rosenvinge joined Township as a junior engineer in November 2021 and recently created new documentation for how to use JSDoc and Typescript for even better documentation in client work. He hopes this will support what-would-be junior engineers and really any team looking to make their code easier understood by others. Check out a little more on his journey and why JSDoc and Typescript are valuable tools to not just have, but use.
Why did you decide to be an engineer?
I was looking for more consistency in my career. I was previously working in event photography, a career that can be unpredictable as amplified by the pandemic. I strive to one day start a family and own a home, and I didn't see that happening as a freelancing artist. Software engineering interested me because it all boils down to problem-solving, and a lot of creativity can be harnessed in that problem-solving process. It just checked a lot of boxes for me.
What were the most critical parts of your onboarding as a junior engineer?
I believe I succeeded and progressed past my junior stage because of the support of more experienced team members at Township. I was also trusted with larger tasks then I anticipated a junior would be responsible for. I was given the opportunity to fail, fix and grow with the support of my peers to ensure the work got done to standard for clients.
What role has documentation played in your ability to be effective?
Quality documentation is essential for effective collaboration in software development. Clean and readable code is important, but complex code segments are inevitable. Therefore, having concise and clear documentation can save time for developers who are new to a codebase or less experienced. A quick 2 sentence plain English description of how/why/where a piece of code works can help prevent misunderstandings, errors, and bugs. Well-documented code can also improve maintainability and scalability by making it easier for developers to make changes and improvements over time.
Why are JSDoc and Typescript important to your day to day? To client work?
JSDoc and Typescript are important to my day-to-day work because they require a slightly larger upfront investment, but can help avoid headaches in the long run. While Township doesn't require every function to include thorough JSDoc comments, we aim to write code that is readable enough to not require extensive documentation. However, we recognize the importance of using well-written documentation when needed and trust our judgment on when to utilize it. Additionally, using Typescript can help catch errors early in the development process, leading to more robust and reliable code. When working with clients, these tools can also help ensure that the codebase is well-documented and maintainable, which is crucial for long-term success.
How do you hope your documentation can be used or built on by other users?
Readability, scalability, and maintainability. This documentation should contribute to setting projects up for long-term success:
How to use JSDoc and Typescript for Documentation⤤
