DEV Community: Mazdak Parnian

Streams in C#

Mazdak Parnian — Thu, 06 Nov 2025 14:24:00 +0000

Before your programs know and understand the content of the information that's being passed over the network, they need a reliable way to transfer and receive information.

Streams offer just that. But before diving too deep in the network side, we need to take a look at streams in general! They are one of the fundamental structures of interacting with data outside of your program (not just through networks)!

When I started out as a developer, they used to confuse me a lot, but hopefully in this post I can help you leave the confusion behind!

The Base `Stream` Class

When talking about streams, we're strictly talking about transferring data; and when your only concern is just moving data, that means that the data is raw bytes. The base Stream class in C# represents that idea wholeheartedly.
The base class only provides direct access to an ordered sequence of bytes, but it doesn't give a meaningful way of understanding the data.

You can think of it as like the Highway over which the data passes through. It's the road, you don't care about what types of cars go through it.

A stream is an active connection to the data source. Like any data source it needs to be opened and closed and then disposed before you're done with it. This should probably make sense to you if you've already worked with external connections such as database connections and such.

External connections mean that our program must interact with the underlying Operating System in order to get what it needs, that also makes our program responsible for the resources the OS is giving it, thus why we need to open, close and dispose of such connections.

The Stream class gives us three important actions: Read, Write and Seek an index of a sequence of bytes.

Writing to Streams

The streams do not bother themselves with how complicated objects are represented. It's simply not their job, they are the road over which raw data travels. so if we want to send data over streams, we first have to convert/serialize our data to bytes (byte[], or byte depending on the size of the data).

var m = "stream data into a file";
var bytes = Encoding.UTF8.GetBytes(m);  

// Notice the ioStream's type => Stream
using Stream ioStream = new FileStream(@"strm.txt",   
    FileMode.OpenOrCreate);  

if (ioStream.CanWrite)  
    ioStream.Write(bytes, 0, bytes.Length); 

else  
    Console.WriteLine("Couldn't write to our data stream.");

Notice the ioStream variables type, it's a Stream not a FileStream. That's because it really doesn't matter where the data is coming from. If we change the FileStream to a NetworkStream, how we work with that stream would mostly be the same.
The Stream class provides us with enough data, that includes letting us knowing if the stream is ready to work with with the CanWrite property. This also, in a small way, helps error handling by avoiding try/catch blocks.

Since streams work exclusively with raw data, they don't bother themselves with anything else. We must provide them with raw data, so no matter what the data is, we must serialize it into a sequence of bytes.

We can convert strings to bytes using Encoding.UTF8.GetBytes method.

In the same way the a stream has no idea of the actual contents of the sequence of data its transferring, it also doesn't know where to start reading and when to stop. it needs the array of bytes, then instructions on where to start reading from, and precisely how many of those bytes it should write.

The second parameter in the Write method signature is your starting index. It starts at 0, just like the array does. The third parameter is the total number of bytes you want to send in this Write operation.
There is a runtime error checking on this and if you try to send more bytes than there are left in the array (starting from whatever index you designate), you'll get an index out-of-bounds error.

You're giving the stream the data, and where to read from that data.

Seek

So far we know how to write to a stream. If you run the previous code multiple times you find yourself a file that doesn't seem to change at all!
In reality, the file is changing. Every time you execute your code, it's opening a stream to the file, and writing to it starting from the files 0 index until the end of the given byte array. But we often need to also tell the stream where to start writing or reading data.

Every time we open a stream connected to a data source, we're getting the complete ordered list of bytes stored at that source, along with a pointer to the start of that array. Every operation we execute on the stream moves our pointer in one direction. If we write 10 bytes, we find ourselves 10 positions further down the array than when we started. So, each of our primary operators(Read/Write) can only ever move in one direction, forward, from the current stream index when we start executing them.

for example, if we write to the stream twice:

var m = "stream data into a file-";
var bytes = Encoding.UTF8.GetBytes(m);

using Stream ioStream = new FileStream("strm.txt",
    FileMode.OpenOrCreate);

ioStream.Write(bytes, 0, bytes.Length);
ioStream.Write(bytes, 0, bytes.Length);

The result would be the same string twice in a row:
stream data into a file-stream data into a file-

We can make the stream read or write from a certain position in the sequence using the Seek method on the Stream instance. This makes the stream to seek that index, relative to the given indexes.

The SeekOrigin enum gives us the three useful origins we might want to use in most cases: Begin, Current, End.

For example in our previous code, if want to stop overwriting the message every time, and actually append a string to the end of the file every time the program is executed, we can simply make the stream fetch the end of the file and start writing to it from there like so:

var m = "stream data into a file-";
var bytes = Encoding.UTF8.GetBytes(m);  

using Stream ioStream = new FileStream("strm.txt",  
    FileMode.OpenOrCreate);  

if (ioStream.CanWrite) 
{
    // set the pointer to the end of the file
    ioStream.Seek(0, SeekOrigin.End); 

    // now write to the stream from the end
    ioStream.Write(bytes, 0, bytes.Length);  
}

We're telling the stream to first go to the end of the stream, and start it's operation from there:

Reading from streams

Each time the read operation is executed the streams cursor moves forward by one index. Data is read one byte at a time. You have to store the data you read in an array, or a single byte depending on your usage, and you have to make sure the array exists before you read.

var m = "stream data into a file";  
var bytes = Encoding.UTF8.GetBytes(m);  

using Stream ioStream = new FileStream("strm.txt",  FileMode.OpenOrCreate);  

if (ioStream.CanWrite)
{  
    ioStream.Seek(0, SeekOrigin.End);  
    ioStream.Write(bytes, 0, bytes.Length);  
}  
else  
    Console.WriteLine("Couldn't write to our data stream.");  

if (ioStream.CanRead)  
{  
    byte[] destArray = new byte[10];  
    ioStream.Read(destArray, 0, 10);  
    string result = Encoding.UTF8.GetString(destArray);  
    Console.WriteLine(result);  
}

While this approach works, there are limitations to it that make the code not-so-clean to work with. There's the issue of using the old-style arrays and their fixed size. It forces you to specify the size of the array, which in hand makes you probably use a reasonable maximum size for the array.

Stepping up from Stream

While the base Stream class opens up a lot of opportunities by giving us meaningful yet simple ways to manipulate streams, a lot of the work is repetitive and tedious most of the times. This is where we move on to more powerful types which ease each process of reading and writing.

JSON

before moving to general readers and writers, it's worth mentioning the most famous specification for data transfer around the web, JSON.
In .NET we have the famous Newtonsoft.Json which is easy and powerful to work with.
Since .NET Core 3.0, Microsoft has developed an alternative, System.Test.Json. the focus of this new JSON library is on performance and fine-grained control over the serialization process. As a result, the feature set of the System.Text.Json library is severely limited when compared to Newtonsoft.Json.

`StreamReader` & `StreamWriter`

Since most of our work consists of using strings to capsulate complex data with json, it makes sense to have types tailored for working with strings.
The StreamReader & StreamWriter classes sub-class the TextReader class from the System.IO namespace, and extend its functionality to interface directly with byte streams.

Even though we're using a FileStream here for demonstration purposes, for real network programming, we'll want to connect directly to a data stream to a remote resource.

When working with strings from remote resources, knowing the specific encoding with which to translate the incoming bytes is key. If a character is encoded as UTF32, and decoded using ASCII, the result wouldn't match the input, rendering your output string a garbled mess. If you ever find a message that you've parsed to be indecipherable, make sure you're using the right encoding.

Using these classes will reduce the amount of work you need to do when working strings to just a few simple lines (if you know what you're doing!):

ComplexModel testModel = new ComplexModel();
string message = JsonConvert.SerializeObject(testModel);

using Stream ioStream = new FileStream("strm.txt", FileMode.OpenOrCreate);
using StreamWriter sw = new StreamWriter(ioStream);

sw.Write(message);

Since these classes are designed to work exclusively with string content, they even provide useful extensions, such as a WriteLine(string) method that will terminate the string you've passed in with a line terminator character. Meanwhile, the ReadLine() method will return characters from your current index up to and including the next line terminator in the buffer. This isn't terribly useful with a serialized object, since you don't want to read a line of a JSON string. However, if you're working with a plain-text response, it can make reading and writing that response a breeze.

Seek vs Peek

Using the reader and writer types don't allow us to set the current index of the stream, for that we have to directly access the underlying stream using their BaseStream property.

var message = "stream test message";  
using Stream fs = new FileStream("strm.txt", FileMode.OpenOrCreate);  
using StreamWriter sw = new StreamWriter(fs);  
sw.BaseStream.Seek(10, SeekOrigin.Begin);  
sw.Write(message);

It's not uncommon to forward search through a string until arriving at a terminating character or flag value. Doing so with the StreamReader.Read() operation will result in moving the index past the terminating character and popping the terminating character off the array. If you want to simply read the last character before the terminating character, though, you have the Peek() operation.

Peek() will return the next character in the array without advancing the current index of the StreamReader.

using Stream fs = new FileStream(loc, FileMode.OpenOrCreate);  
using StreamReader sr = new StreamReader(fs);  
while (sr.Peek() >= 0) sr.Read();

The result of the above code is that the stream index will be exactly on the termination character. This also means that the stream is closed and write is unavailable.

The `NetworkStream` class

This class behaves exactly the same as the FileStream class. The only difference being that it's underlying type is an instance of the Socket class.
All the operations we did on the FileStream class work on this type as well and it can also be the BaseStream of an instance of the StreamReader/Writer classes we've seen.

This type will be important when you want to implement your own socket connections.

Most stream operations have concurrent variations as well. This greatly improves the performance of your application since some stream operations will be heavy and time consuming.

An example of how to work with networks using the stream types that we've learned so far with their concurrent counterparts:

public async Task<Result> PostRequestAsync() {  
    var result = new Result();  

    var request = WebRequest.Create("http://test-domain.com");  

    request.Method = "POST";

    Stream reqStream = request.GetRequestStream();  

    using StreamWriter sw = new StreamWriter(reqStream);

    await sw.WriteAsync("Our test data query");   

    var webResponse = await request.GetResponseAsync();  

    using StreamReader sr = new StreamReader(webResponse.GetResponseStream());

    result.RequestResult = await sr.ReadToEndAsync();

    return result; 
}

This concludes the basic stream foundations that we'll need when working with networks in .NET, There are other types that inherit Stream and are for other purposes, but I'm sure by now you've understood that all those types do, only convenients working with the basic underlying Stream type (just like we saw with StreamReader/Writer for strings).

There are other types that are specifically made for working with files and directories, but you can go and see their implementations, it all comes from streams.

I hope I could give some useful context to you!

Intro to The Network Programming Series

Mazdak Parnian — Thu, 06 Nov 2025 13:58:52 +0000

Working with networks always seems intimidating, specially when starting out. From my earlier days a software developer, networking concepts seemed difficult to get around. Even after I took a Network+ course to understand the fundamentals of networking, it was the development side of things that had me sweating. Like all things difficult, I tend to jump in hot instead of running away!
So I searched around and found myself a book, "Hands-On Network Programming with C# and .NET Core" by Sean Burns. The name pretty much explains the book. I wanted something to show me .NETs capabilities with networks and the book seemed like a great start to that.

What is Network Programming?

By now there's a chance that some of you are wondering, what really is network programming?
At first it might sound like some guru sort of coding! But what it really means is writing programs that utilize your Operating Systems networking capabilities and allow you to control them to your benefit.
Any sort of program that uses a network falls under that category; things like setting up a lan, using FTP to transfer files, using a GET HTTP Request to get some data from a server, the list goes on. There's a really good chance that you've done some sort of network programming without even knowing the term!
As backend developers, our work involves setting up networks most of the time, more specifically, setting up HTTP servers and providing/consuming resources over the network.
It bothered me that I felt like I was using some blackbox to setup my servers. I like knowing what's happening under the hood. Plus, it's not just about knowing! There's a lot of things that the framework offers that you can use to solve your challenges and knowing more never hurts.

What Is This Series?

One thing about learning (niche) topics like this, is that you most definitely will forget some parts. Not that it's a bad thing, there's just too much information and it's mostly good to know what exists and look for details on it later.
So I thought I'd start a series on the topic, keep things organized so I can find the important stuff later again, and also share the good stuff with YOU!

Prerequisites

While the book firstly covers networking basics and concepts, I don't want this to be the book. If you really have no idea what networks are, or what's an IP, or protocols like HTTP or similar topics, the series would probably confuse you more and I suggest you read on networking fundamentals. There are great sources for that on the internet in any form you prefer, or you can simply read the book I mentioned earlier, it covers all the concepts one needs to know to get started with networks.

What I'll Cover

I want to cover the practical side of networking. Mostly how .NET does things and how to work with the tools the framework offers. Some examples could include:

Streams
Sockets & Ports
FTP
TCP & UDP
Security
Analysis & Packet Inspection

These are the sort of topics that interest me and they are why I decided to dive deep in networks! I hope you also find the series useful! Be sure to keep in touch if you have any suggestions or questions!

Learning Go as a .NET Developer

Mazdak Parnian — Fri, 08 Aug 2025 16:27:10 +0000

I've been a .NET developer for 3 years now. Throughout my journey I've learned so much, and at the same time, I've had a lot more questions. The .NET ecosystem is big and mature, but the learning curve is also noticeable. From the C# language itself to the ASP.NET Core framework and all the tools one needs to know like Entity Framework. Sometimes I wondered if other languages have this much to offer as well. I've always been a practical hands-on type of person. I like to know how things work, and how I can make them better.
One of my favorite things to do is having technical discussions with my developer friends. Talking about how things work, interesting challenges we've faced, fun things we've done, etc. One of them is a Go developer. Before talking to him, I knew of Go, but I had no idea what it looked like. But very quickly it got my attention.
I liked the core philosophy of the language, **Simplicity.
The Go programming language aims to keep things simple all the while giving you the power to do anything you want. Anything you can do in C#, you can do in Go.

You can check the language out here!

I studied The Go Programming Language book. It's an amazing starter book. you can find it here!

Memory Management & Garbage Collection

While learning about memory management in Go, I realized how similar it is to C#. Both languages use a garbage collector.
C# has reference types and Go has safe pointers. At first glance they looked and felt like each other. Both reference types and safe pointers aim to cover the un-safety of pointers. They actually behave quite similar.
In Go whenever you want to pass a reference you simply pass a pointer to the variable, and the pointers can be nil, Go's null construct.

// C#
SomeMethod(person) // classes are reference types by default

// Go
someMethod(&person) // looks like c-based pointers, but it's safe!

Functions

Go functions can return multiple values by default. In C# it's kind of similar to using Tuples but it's not exactly the same, but looks like it. Since it's part of Go it allows the developers to use "The Result Pattern". We'll talk about this more in "Error Handling".

// C#
// using Tuples to return multiple values
public (int v1, string v2) SomeMethod() {}

// Go
// returning multiple values
SomeMethod() (v1 int, v2 string) {}

In Go, the returned types come after the parameter list of the function, unlike C#.
You might have also noticed that the type of the variables come after their identifier in Go!

The Compiler

The compiler is where Go shines more than C# in my opinion. The compiler acts as a major safeguard here. A lot of the bugs show up at compile-time. The language doesn't have a JIT compiler unlike C#. Go uses the compiler to enforce the syntax in a stricter manner.
For example, your variables must be used otherwise that's a compiler error. This helps a lot with removing unnecessary memory allocation. Returned variables from functions must be used or explicitly discarded.

// Go
SomeMethod() (v1 int, ok bool) {}

SomeMethod() // compiler error! returned values not used!

I feel safer and more comfortable with Go's compiler.

Concurrency

C#'s concurrency model, is vast. You have multiple ways to make something concurrent. each one has it's own challenges and merits. More importantly it requires you to know it well before using it. While it's a powerful system, it can be daunting to start with. It took me some time to get used to and learn beyond async/await.

One of the very first things that caught my eye when I started learning GO was it's concurrency system.
Go has a CPS-Style (communicating sequential processes) concurrency model. What does that mean? Wikipedia says:

communicating sequential processes is a formal language for describing patterns of interaction in concurrent systems.

This short article is useful as well if you are interested.

You can learn Go's concurrency patterns effectively using Concurrency.Rocks!
Due to how big this topic is, I'll link to the website rather than showing code here, It's a much better learning material for this topic!

Goroutines

Goroutines are lightweight concurrency constructs which allow one to run functions in the background. The syntax is straightforward, any function you want to run in the background, simply put the go keyword behind its call. No more async/await, no more Task or Thread. It simply does what it should. You don't need to worry about threadpools, creating manual threads, using TaskCompletionSource, none of that.
A notable thing about goroutines is that you can't have them return something. To get a value from a goroutine, you have to use Channels, another interesting GO construct.

Channels

Channels are something that you'll face early when learning the language. Channels are another concurrency construct. They allow use to safely pass data in our program in a thread-safe manner. Think of channels as an in-memory message queue. While there's more to it, this isn't a Go tutorial so I won't be showing too much syntax.

Error Handling

Handling errors is also one of the thing's where the two languages differ from each other significantly.
C# and other C-Based languages mainly use exceptions to handle error. There's been a lot of discussions about the performance of exceptions in recent years. Go uses something called the "Result Pattern" in the world of software. What that means is that it basically returns whether the function resulted in an error or not. Though this isn't a syntax only for errors.
In the Functions section we talked about returning multiple values from functions. Well, by convention, there are two types of fault handling we can have:

Returning a bool value named ok as the last returned value SomeMethod() (v1 int, ok bool)
Returning an error which is a struct in the standard go package SomeMethod() (v1 int, e error)

Both of these methods are used regularly in Go programs. This reduces a lot of the performance problems with exceptions while making sure one point stands throughout your program:

A good program knows whether it'll return an error or not.

Exceptions are unknown. Specially when you have a global catch(Exception e). A good program should know what types of errors, if any it'll return and handle it gracefully, Go emphasizes on this.

Why Go?

Now you might think, where would I use Go? For me, .NET is still the language to write my Apis in. The ecosystem is just too mature, and having put the time in to learn it, it's actually quite enjoyable to develop applications in .NET. Each language is a tool and each one has strengths in it's own place.
Go's simple yet effective concurrency model makes it the perfect tool to handle a lot of calls for simple methods, while C# is more focused on delivering business quality allowing one to develop complex businesses. I don't like the feeling of being too dependent on one language.

Go is a Modern Language

It was designed at Google in 2007 by Robert Griesemer, Rob Pike, and Ken Thompson, and publicly announced in November of 2009. - Wikipedia

Go learned a lot from it's predecessors. It aims to please with it's powerful simplicity. One thing which caught my attention about the language was that it felt "low-level" while still being a "high-level" language. But maybe that's just me comparing the syntax to C#.

Not having a Just-In-Time compiler also means it's much easier to build your program for different OS, Although not that it matters anymore since .NET has become cross-platform recently. But that still makes the executables more lightweight and easier to port. I would actually prefer writing system programs, cli tools and other similar type of programs in go instead of .NET, it just feels right with Go.

Another way learning Go has helped me, was making me deepen my knowledge in C#. When studying the language, I often questioned myself on how I would achieve the same result of a program in each language. One example was Channels. I quickly realized that C# also has channels and that it was added in .NET Core. I remember how happy and excited I was!
By learning how two or more languages approach the same challenges and problems, one can develop better software knowing what happens underneath all the cute interfaces and Apis. Languages and frameworks are tools one learns to apply. We often forget why we learn programming. To solve problems. Just because you know one language doesn't mean you can't learn another. Software development is all about depth and perspective!

I hope this gave you some insight to the Go Programming language and maybe it made you want to try it out!

Making a Thread-Safe Cache in .NET

Mazdak Parnian — Mon, 21 Jul 2025 10:20:43 +0000

One of the challenges that we will face as a developer is the problem of accessing a resource from multiple threads. Handling concurrency and shared state between different threads is a delicate and important feat.
Today we'll look into the problem of accessing a Cache/Dictionary in a thread safe way.

The Problem

suppose we have a cache that holds data that we fetch from another server. A consumer calls the cache to fetch data for a key, and if the cache doesn't have the data, it must download it.

static Dictionary<string, DataModel> _cache = []

public async Task<DataModel> GetValueAsync(string key) 
{
  if (_cache.TryGetValue(key, out data)) return data;
  return _cache [key] =
    await new DownloadDataAsync(key);
}

This approach is generally fine and thread-safe and we don't need locking for safety. Until two threads try to get the same key value from the cache. In that case there will be multiple download requests for the same data, each updating the same cache entry. While this still won't cause an error, it can affect performance.

The Solution

The solution is interesting and easy. Instead of keeping the value directly in the cache, we keep it's future. So the cache holds Task<DataModel>.

static Dictionary<string, Task<DataModel>> _cache = []

public Task<DataModel> GetValueTask(string key) 
{
  if (_cache.TryGetValue(key, out dataTask)) return dataTask;
  return _cache [key] = new DownloadDataAsync(key);
}

This way, we'll always get the same Task for each DataModel if we call the GetValue method with the same key over and over, and if the Task is complete awaiting it has low cost. This approach also reduces the load on the Garbage Collector.
Notice that we're not using the async/await keywords here since we need to return the tasks themselves not the actual value.

To make it truly thread-safe we lock the operation. Though the lock will be very short since we're only locking for the duration of a lookup and quick add to the cache, since the actual downloading will be done inside the Task and not in the GetValueTask method.

static Dictionary<string, Task<DataModel>> _cache = []

public Task<DataModel> GetValueTask(string key) 
{
  lock(_cache)
    if (_cache.TryGetValue(key, out dataTask)) 
      return dataTask;
    else
      return _cache [key] = new DownloadDataAsync(key);
}

Although there are ready-made constructs to achieve similar designs, it's important to understand the underlying techniques used in their making.

I hope this helps! Ask me any questions you might have about concurrent caches!

I Created a .NET 8 Web Api Project Template

Mazdak Parnian — Fri, 01 Mar 2024 12:01:58 +0000

Introducing My Web API Project Template: A Time-Saver for .NET Developers

Are you tired of spending hours setting up a new Web API project from scratch? I know I was. That's why I decided to create a project template that includes all the essential features I need for my Web API projects. This template is designed to save you time and ensure a smooth development workflow.

Why This Template?

I am sure there are lots of project templates out there which make setting up new projects faster and easier. But I also have a habit of doing things for myself. So When I had to setup a Web API project in .NET 8, it took a while to setup all my desired features.

Features

Setting up a Web API project in .NET 8 can be a daunting task, especially when you want to include specific features like:

Entity Framework Core for robust data access
Swagger with API versioning for easy API documentation and testing
NLog for comprehensive logging
SignalR for real-time communication

I've spent some time configuring and testing these features to ensure they're development-ready. Now, I'm sharing this template with you to help streamline your project setup process.

How to Use the Template

Note: I have created and tested this template in Visual Studio 2022 version 17.8. It should work in version >17.0.

Download the Template: Visit the GitHub Repository of the template project.
Get the Template File: Download the template file from the Release section of the repository.
Copy the Template file to C:\Users\{User}\Documents\Visual Studio 2022\Templates\ProjectTemplates
Create A new Project and select the template from the list of templates. If you don't see the template search for it.

Customize and Use

Feel free to customize the template to fit your project's needs.

Need Help or Want to Contribute?

I'm always open to feedback and contributions. If you have any suggestions for improvements or encounter any issues with the template, please don't hesitate to contact me.

A Friendly Intro To Software Documentation

Mazdak Parnian — Tue, 09 Jan 2024 17:44:28 +0000

Documents are such an underrated thing. We all love good documentation when we see one, but when it comes to writing our own documentation, that's where it gets tricky!
Today we're going to discuss documentation, its role in software and development, and why it's better to spend company resources to create and maintain it.

Why Documentation?

There has always been a love-hate relationship between developers and documentation. We love it when we consume it, and it's the most difficult thing to make at the same time. Because everybody knows, right? Or, good code documents itself. We've all heard these infamous lines somewhere down the road. Maybe at some point, we thought to ourselves, "Well, the code I have written seems pretty easy. How can someone not understand this?"
While that may be true in some cases, it often causes more trouble than it seems.
Documentation helps keep track of where the project is headed while preserving its current and past state.

Project

There are many stages in the project's lifetime. Some of them can include meetings with the stakeholders. Documents help clearing the air by providing transparency about:

The project
Where it is headed
Its current state

It eases the process of change in the project, which can be a change of managers, features, developers, etc.

Development

Developers use documentation all the time. You don't have to be a major company to use documents. Suppose you are a small team of developers with a few people in each section (front-end, back-end, infrastructure, etc.). Having documentation in each section helps other teams manage their work with less entanglement between people.
John doesn't have to call Ellis to ask about the project APIs or ask for a sample request to call a service. With proper documentation, he can simply look up the documentation for that service and get most of the data he needs.

Speeding Up Recruitment

It's much faster and easier to read documentation about something rather than having to look for someone to explain it. When there are new employees in the company, it is very convenient to have them read the documentation because:

It saves company resources. This way, the company doesn't need to assign another employee to get the newcomers up to date with everything.
It is up-to-date with the company's projects and latest developments.
It has enough information a newcomer needs to get started.
It allows them to get familiar with the working environment and how projects are handled in the company.
It can be a faster approach because people might learn faster if they do it at their own pace.

Make Better Documents

Now that we know why we should use documents, there are a few things we can keep in mind to make better documentation.

Implement Documentation in your Development Cycle

Starting documentation for a project can be a huge thing. Specially if the project has been going on for some time. The first thing to understand is that:

Documentation is a part of software development.

So don't think little of it. It is something that needs its own dedicated time during development, and for good reason. So don't think that it is something that can be done in a few days, and you're done. No.
In order to have useful and effective documentation, you need to implement it in your development cycles/sprints/iterations. Dedicate a part of your company's employees time to documentation, and don't make it sound unimportant. Sure, you'd like to get that feature done quickly, but you also need to have that feature documented so the next person working on it can have an easier time developing it.

Think Outside the Box

I was reading a book on software documentation. It mentioned something very important when writing software documentation, The Curse Of Knowledge. When you are writing documentation about something, you have a certain level of understanding about it. You don't need to be the master of that thing, just enough to make others understand too. But when we are transferring knowledge, we tend to forget that other don't know.
"It's such an easy thing; how can someone not get it?"
But we easily forget the amount of energy and time we put into learning something. So it's easy to overlook important things in the document and miss out on a few things here and there. These things add up, and suddenly we find ourselves with a piece of vague documentation that creates more questions than it answers.
In order to avoid this tricky situation, here are some things you should consider before writing documentation:

Who are you writing the document for?
What is their level of knowledge? What is the prerequisite for this document?
What kind of information are you trying to transfer? Is it a tutorial? a reference? a starting guide?
What can the audience do wrong? for example, if they click on another button, fill out the wrong form, or enter the wrong information? Keep everything in mind.

Don't Overthink It

Writing documentation is not rocket science. However, it easily gets overwhelming when we think about all the things we want to write. It's important to write just the right amount of documentation, but at the same time, it can get out of hand very quickly. Try to have your documents reviewed by multiple people, like the audience you are writing for.
For example, if you are writing documents for a customer, have them read them and tell you if they have any problems with them. Or have someone who knows the topic read it.

Feedback always helps.

Try not to bombard the reader with too much information. Keep it just enough, but don't forget the edge cases of what they should know and should not.

Final Words

While writing software documents can be a slow and boring task for many, it is almost always worth it. Don't let anyone tell you otherwise. It can cost you, but developing good software comes with costs.
I hope this article has helped you find your way with documents.

The Start Of My Blogging Journey

Mazdak Parnian — Sun, 17 Dec 2023 12:47:30 +0000

I have been thinking about doing this for a long time now. There are many reasons as to why I wanted to do this. I'll get to them shortly. But first, a little about me. I have to let you, the readers of this very first post, know who I am and what you are doing here.

Who Am I?

I am a junior software developer from middle east. I have started my professional career for a little over a year now. But this wasn't my first contact with the world of IT.
I started getting interested in IT at highschool. I started learning Python and soon my path crossed with the world of Linux. But for a long time I didn't do anything major or think about this as my career in a way I should've. But still I chose Software Engineering as my bachelors topic. This just made me fall more in love with the world of computers.
currently I am still a student. But soon I will finish my bachelors degree.

My Skills

I am a .Net developer. But I wasn't always on .Net.
My career started as a NodeJs developer. But soon I realized I wanted to be a professional in a language that has a huge company backing it and is frequently used in major organizations and such. There is absolutely nothing wrong with being a NodeJs developer and generally, its just a matter of preference. But for me the switching to .Net was the perfect choice.
I am also good at working with Databases. I have taken a deep course on MSSQL server. But I also have worked with MongoDB from the days I was hired as a NodeJs Developer.
I have a deep love for Linux systems. This goes a little opposite ways since .Net is a Microsoft product and works best with windows servers. But still, I feel most comfortable when I am working with a Linux server.

My Job

I started my first .Net job about 6 months ago. It was just after I finished my second project in C#. I started learning C# just after the new year holidays in my country. before the new year I quit my NodeJs job because I didn't see a future in it for me and I felt like I wasn't a good enough backend developer.
So I started learning C# with a course. Then I finished a course on .Net 6 and MVC and then I quickly finished a course on Authentication and Authorization in .Net. this all took about 2 months for me. Thus began the time to send resumes. It took a month or two for me to find a job. I was very inexperienced. But I had confidence.
My first job as a .Net developer was found after some time. I am still working there and I am very happy about the place I work.
I develop and extend Microsoft Dynamics 365/CRM solutions with .Net. It took me a month or two to finish my training in D365, and I continue to learn more about it everyday at work.

Why Blogging?

Since my first days of getting to know the world of computers until now, I have had a deep passion for teaching all the cool things I have read. I have considered creating a course multiple times. But creating courses or video content for Youtube takes a lot of time and dedication. So I thought, if I zoom out of video content, I have podcasts and blogs. It sounded like a wonderful idea to me. It lets me put less time into content creation all the while giving back the knowledge I have gained to the world.

What It Gives Me

Another reason for creating such content is that it allows me to track my own progress like a sort of journal. It lets me compare myself to my past and see where I have come from.
Also, I think it would be a good idea to also create content that non-tech people can benefit from. After all this is the age of technology and almost all people need to have a basic understanding of computers.
I enjoy explaining my work and things I learn to my non-tech friends and this blog gives me a channel to direct my energy to.

How It Inspires Me

Thinking about explaining things, has always made my brain engines start. There's that famous saying which tells us we will only have learned something when we can transfer that knowledge, which at least goes very true for me.
Another reason which creating content helps me is that it makes me want to learn more myself, so I can teach more. Throughout the day, at work or at university, I hear a lot of useful stuff like new technologies, news, the right way to do something, and many other peoples experiences. All of those inspire me to transfer them in my content and give back to the community.
After all, the world of technology has only improved because of its communities contribution.