Documentation Wasteland – Dev Leader Weekly 22

Hey there!

Welcome to another issue and huge thanks to both the new and previous supporters! I have more exciting news that some new faces might have seen online which prompted them to subscribe — There’s a book giveaway from PACKT publishing! All of the details are in the Learning Resources section, so make sure to check it out.

This week’s exclusive article is on documentation. If it sounds boring to you because it’s not about coding, I urge you to at a minimum check out the key takeaways. Documentation is a big part of most software engineering orgs – for good or bad. It might not be the most sexy thing to focus on, but I always talk about focusing on pros and cons of things… Documentation is a great example of balancing pros and cons.


A quick reminder that you can refer your friends to sign up for my newsletter! You can get free membership access for a few months to my site to access the newsletter archive and my Behind The Screen weekly vlogs that I do. Check out the details at the end of this issue.


What’s In This Issue


Exclusive: Documentation Wasteland

Documentation – By Request

This topic comes to me from LinkedIn where it was requested I share some thoughts on internal documentation and how do do it properly. And what a JUICY topic this is because it gets people really divided really fast. Nobody seems to be able to agree on the best way to accomplish this.

However, I think the one thing people DO agree on is that the concept of having documentation is valuable. Being able to have a history or record of information, decisions, events, etc… is hugely valuable.

But the problem is that documentation doesn’t come for free. In fact, documentation can be extremely expensive. In this article I’m going to share my thoughts on different types of internal documentation and give my recommendations.

Follow along with this week’s exclusive video:

YouTube player

Onboarding Documentation

Onboarding documentation is extremely beneficial for new team members, helping them to quickly understand and adapt to the team’s processes and culture. It can also be advantageous for different teams to share common onboarding materials, promoting consistency across the organization. Shared onboarding documentation is almost like refactored and reusable code — yes please!

However, the initial creation of this documentation often falls on someone’s shoulders, which can be a daunting task. A practical approach might be to have new team members contribute to this documentation, reflecting their fresh experiences and perspectives. A major drawback of onboarding documentation is that it tends to become outdated relatively quickly, necessitating regular updates to remain useful and accurate.

One of the best ways I’ve found to address this is to nominate the next person onboarding to help. Tell them that they get to champion updating toe docs just like the person before them. When we talk about “boy scouting” in refactoring and code cleanup, I am 10000% on board with this for documentation.

Troubleshooting Documentation

Troubleshooting documentation is a valuable resource when dealing with recurring issues. It typically includes step-by-step solutions to common problems, making it easier for team members to find and apply fixes.

On the teams that I manage now at Microsoft, we have “battle cards” for helping our on-call engineers. These are a great resource to turn to because the complexity and variety of issues that can arise is… very great. Using prior knowledge is our key to success.

The downside is that this type of documentation often becomes outdated, which can lead to misplaced confidence in its solutions. Additionally, it’s challenging to cover every possible scenario, meaning that some problems may not be addressed in the documentation.

This always makes me wonder though… If we were able to document the step-by-step investigation and possibly resolution, why can’t we automate portions of this?

Design Documents

Design documents are crucial for capturing and iterating on ideas. They allow for collaborative input and refinement, making them an integral part of the creative process within a team — or even across teams when there are varieties of stakeholders.

At Microsoft I’ve seen “one pagers” (or sometimes it’s more like a few-pager) as well as much more detailed design docs float around. I think the biggest benefit to this that I see is the collaborative nature where folks can comment and adjust as necessary.

However, these documents can quickly become outdated if the project’s design changes during implementation. And the reality is, the bigger the project being designed, the more likely reality won’t line up. Therefore, it’s important for design documents to be updated alongside the project to maintain their relevance and usefulness. This is significantly less likely to happen in practice just because it’s extra work, so try to make an effort.

Planning & Work Items

Documentation of planning and work items serves as a record of customer feedback, learnings from completed projects, and reasons behind specific decisions. This type of documentation is beneficial for historical reference and for understanding the evolution of projects and decisions.

One challenge is the potential chaos caused by using multiple documentation systems simultaneously, which can lead to disorganization and difficulty in synchronizing information. Additionally, there can be inconsistency in the way items are documented, such as varying issue types and recorded details.

Especially when it comes to planning documentation. another issue is the tendency to focus excessively on minor details. There’s a great degree of bike-shedding often at the expense of more important content. Try to remember that this kind of documentation is a tool and turning it into busy work doesn’t help a single person.

Code Documentation

Code documentation is a significant part of a software engineer’s work, as it involves reading and understanding code. Comments within the code that explain the rationale behind decisions can be particularly helpful. We often want to write code that is as expressive as possible, but there are certainly cases where the code itself doesn’t explain WHY a decision was made.

However, many code comments are redundant, adding unnecessary clutter and maintenance work. The need to maintain these comments, especially when they are redundant, can effectively double the maintenance effort required for the code. For example, if you’re commenting to repeat what the logic does, or you’re repeating what the magic number is even though there’s a well named constant for it… it’s just extra!

If you’re going to comment – use them sparingly to convey additional context that is important for the reader. If you can do the same thing by naming your things better — do that.

Documentation Takeaways

The main points here are that documentation is valuable — but it’s not free. Think about what you’re trying to get out of your documentation and try to understand the associated maintenance with it.

Old out of date documentation is like having a flaky unit test. It was supposed to serve a purpose but it’s causing more headaches now.

One of the best ways to keep documentation up to date is to use the “boy scout” technique to leave it better than when you got there. Try it out!


Quote of the Week

Improve Through Retrospectives - Dev Leader Quote

You’ve probably heard before that we learn through our failures (or at least that we should). You’ve probably also heard that it’s important that we create safe places for people to fail so that they can experience these learning opportunities. Of course, the goal is not to fail but rather to leverage the opportunity as a way that we can grow and improve.

But it doesn’t just happen on its own. We don’t always simply “learn” purely by failing. Not if we stop right there!

We need to actively reflect on the scenarios where things went wrong. This reflection process is a retrospective, and it allows us to analyze the different aspects of what went well and what could be changed for next time.

When we’re working in teams this is a critical part of growing together. Becoming an effective and cohesive team takes time, trust, and respect for one another. Going through these retrospectives will allow you to collectively analyze and understand opportunities to improve.

Understand, celebrate, and try to repeat the things that went well. Analyze things that didn’t go well so that you have mitigations for the future and new approaches that you can try for next time.

Keep that safe place to fail, but make sure you’re reflecting on things!


I didn’t get as many articles as I was hoping to this week, but the videos are familiar if you checked out last week’s newsletter!

Fixed The WRONG Bug – Let’s Debug My ASP.NET Core App

YouTube player

After my first bug-fix-gone-wrong, this is how I attempted to remedy things. Of course, things don’t always go as smoothly as we hope… but that’s the realness of creating software.

ASP.NET Service OVERFLOWING With Errors! – Debug & Fix!

YouTube player

And in case it wasn’t obvious from the previous video… Things didn’t get better. In fact, they got worse. This video elaborates on that and FINALLY squashing the last bug… right? Please let there be no more bugs…

The BEST Way To Learn From Your Development FAILS

YouTube player

Refer back to the quote earlier in this newsletter because this video is alllll about reflecting on mistakes. It’s an opportunity to learn what went wrong and what could be improved for next time.

What Is The Adapter Design Pattern? – Beginner Questions Answered

What Is The Adapter Design Pattern? - Beginner Questions Answered.webp

This article is another entry on design patterns! In this article, I focus on the adapter pattern and explain how and why it can be leveraged in your programs!


Learning Resources

C# 12 and .NET 8 – Modern Cross-Platform Development Fundamentals

Full transparency: I was sent a copy of this book and asked to give my opinion about it, and I opted to do so. After last week’s newsletter, Packt has offered to provide books that I can give away to subscribers! This is the extent of my relationship with Packt – They are not paying me for my opinion but I asked them to explore this giveaway prize opportunity after last week and they were interested.

GIVEAWAY CONTEST – Eligibility for Winning

To win this book by Mark. J Price, simply be subscribed to the newsletter! I will be drawing one of my subscribers to win this book and Packt will send it over. That’s it! That means if you’re reading this and it’s not the archived version of the newsletter… You have a chance already!

But there’s more!

Every newsletter referral that you use with your exclusive link at the bottom of this email will enter you for a chance to win the NEXT draw for a book from PACKT! Not only can you win this one, but if you get referrals in, you’ll have a shot at another book!

Insider scoop: The likelihood of winning via referrals is significantly higher. Heads up 🙂

Thoughts on the Book

I’ve had many people ask me, especially when starting, what books they recommend to read as a developer. I never have a good answer though, and that’s because I don’t read books. And no — I am not against reading books. I find that I learn much better by doing and I get bored from reading instead of creating. I’ve always been this way.

When this book showed up at my house my jaw hit the ground. It’s 800 pages. It’s enormous. I can’t imagine anyone reading this front to back, but that’s NOT a criticism of this book. I think people could get a ton of value out of this by treating it like a mini encyclopedia. There are hundreds of pages addressing the language features with examples. It’s nuts!

Because I spend much of my outside-of-work time working on my nutrition platform and then trying to publish more “evergreen” content, I often miss out on some of the newer language features. I’ll be certain to give this a scan specifically on those sections so I can catch up.

If you’re the kind of person who learns from books — especially if you’re new to C# and want to have what feels like every possible language feature covered — I’d definitely recommend picking it up. Please remember that I make nothing from this (there’s no affiliate link or anything), I’m just trying to be helpful if this is a way that you find works well for you to learn!


Solution to Last Week’s Coding Challenge

Did you try out last week’s coding challenge? This involved making an application that could pull web data, putting you on the opposite side of the default ASP.NET core web app project. I don’t have a specific solution to provide you like with the smaller coding challenges but I’d love to know what people created!!


This Week’s Coding Challenge

Build a Simple Task Tracker in C#

Challenge Overview: This week’s challenge involves creating a basic task tracking application in C#. Your task is to develop a console application that allows users to manage their to-do list, adding and removing tasks, and marking them as completed.

Problem Statement:

  1. Task Management:
    • Implement a system to add new tasks, each with a short description.
    • Allow marking tasks as complete.
    • Provide the ability to remove tasks from the list.
  2. Displaying Tasks:
    • Display a list of all tasks, along with their status (complete/incomplete).
    • Optionally, allow filtering to show only complete or incomplete tasks.
  3. Data Storage:
    • Tasks should be stored in memory (no need for persistent storage across sessions).
    • Consider using a simple class or struct to model a task.
  4. Console Application:
    • Create a console application that lets users interact with the task tracker through a text-based menu.
    • Include clear instructions and commands within the console for user interaction.
  5. Error Handling and Validation:
    • Ensure your application gracefully handles invalid inputs and displays user-friendly error messages.

Example Interaction:

Welcome to your Task Tracker!
1. Add a new task
2. Mark a task as complete
3. Remove a task
4. View all tasks
5. View incomplete tasks
6. View complete tasks
7. Exit

Select an option: 

Tips:

  • Begin by defining how you’ll structure a task – what information does it need to contain?
  • Consider how to store the list of tasks. A List<Task> could be a straightforward choice.
  • Focus on one functionality at a time: start with adding tasks, then implement viewing, and so on.
  • Aim for a clean and user-friendly interface in the console.

This challenge will help you practice basic C# concepts, including classes, lists, and user input handling. It’s a great way to see how a simple application comes together and functions. Happy coding!


As always, thanks so much for your support! I hope you enjoyed this issue, and I’ll see you next week.

​Nick “Dev Leader” Cosentino
[email protected]

Socials:
Blog
Dev Leader YouTube
Follow on LinkedIn
Dev Leader Instagram

P.S. If you enjoyed this newsletter, consider sharing it with your fellow developers. Let’s grow our community together!

author avatar
Nick Cosentino Principal Software Engineering Manager
Principal Software Engineering Manager at Microsoft. Views are my own.