DEV Community: Arto Baltayan

Docs-as-Code: Why Documentation Should Live With Your Code

Arto Baltayan — Sun, 22 Mar 2026 17:35:51 +0000

If not well maintained, a major problem with documentation is that it
falls behind the software it describes. Changes are made, a feature gets
updated, parameters are renamed, but the documentation still reflects
the previous version. Developers trying to understand a system through
the existing documentation are left confused.

Docs-as-Code aims to solve this problem by treating documentation the
same way developers treat code, rather than something completely
separate. In this approach, documentation is written, versioned,
reviewed, and published using the same tools and workflows used to build
the software.

Tools such as Git and platforms like GitHub make this possible. Let's
take a closer look.

What Docs-as-Code Means

Docs-as-Code is a simple concept in theory. In practice, the learning
curve can be a bit steeper, especially for technical writers unfamiliar
with the tools commonly used by software engineers.

At its core, Docs-as-Code means that documentation should live alongside
the code it describes. Instead of writing documentation in a separate
system like a wiki, it should be stored directly where the code exists.
In other words, documentation files (often written in Markdown) should
be located in the same repository as the application or API they
describe.

Because the documentation lives in the same repository, it becomes part
of the same workflow, evolving at the same time and in the same way as
the application. When a new feature is added, the updated documentation
can be included in the same commit or pull request.

A Docs-as-Code workflow might not look much different from what an
engineering team is already used to:

A developer adds or changes a feature.
Documentation for that feature is updated in the same repository.
Both code and documentation changes are reviewed through a pull request.
Once approved, the changes are merged together.

In this way, the documentation reflects the changing code. It is not
lagging behind—it evolves alongside it.

Why Teams Should Use Docs-as-Code

More organizations are adopting Docs-as-Code as part of their
engineering workflow. Following are two of the most compelling reasons.

Version Control

When documentation lives in the same repository as the code and is
tracked by Git, team members can see exactly what changed, when it
changed, and who made the change. If something is incorrect or unclear,
it is easy to revert to a previous version.

This level of visibility is rarely available in traditional
documentation systems. It comes from treating documentation files the
same way as source code, rather than storing them separately.

Collaboration

With this approach, documentation engineers and developers work in the
same space, alongside each other. This makes collaboration more natural
and efficient. A pull request that introduces a new feature can include
the corresponding documentation updates, allowing reviewers to comment
on both at the same time.

This shifts the mindset of documentation being treated as a separate
task. Instead, it becomes part of the normal engineering workflow. The
result is straightforward: documentation stays current because it
evolves with the code.

The Challenges of Docs-as-Code

Docs-as-Code has clear advantages, but it also comes with challenges.
The most significant barrier is the learning curve.

Technical writers and documentation specialists need to become familiar
with tools commonly used in software development. This includes
command-line tools, markup formats like Markdown, and version control
systems such as Git.

Without a basic understanding of these tools, it can be difficult to
keep up with the workflow. A certain level of technical knowledge is
required, and for some teams, that adjustment can take time.

Conclusion

Docs-as-Code represents a shift in how engineering teams approach
documentation. Rather than being an afterthought, documentation becomes
an integrated part of the software development lifecycle.

When documentation lives alongside the code, it becomes part of the
normal workflow. This helps ensure that it evolves with the application,
making it easier to maintain, more up to date, and more accurate.

That is the ultimate goal: documentation that actually serves its users
well over time.

Understanding C++ Pointers: The Power Behind the Address

Arto Baltayan — Sun, 22 Mar 2026 17:07:11 +0000

Why Raw Pointers Still Matter

If you truly want to understand what's going on under the hood, you
need to understand raw pointers.

If you are a C++ developer, you've probably been encouraged to use smart
pointers like std::unique_ptr or std::shared_ptr. These are powerful
abstractions and, quite frankly, much safer to use in most cases.
However, they are still built on top of raw pointers.

If you truly want to understand what's going on under the hood, you need
to understand raw pointers. You may never need to use them directly, but
learning them gives you a solid foundation and a clearer understanding
of what's really happening.

Back when I was learning to code, raw pointers were the only option
available to us. To use them effectively, you had to become disciplined
about memory management. You had to think carefully about how and when
memory was allocated and destroyed on the heap. If you didn't get this
right, that's when you ended up with memory leaks.

Knowing how to use pointers---and how memory is manipulated---isn't
just about syntax. It's about understanding the machine.

So that brings us to the question: what is a pointer?

Simply put, a pointer is just another variable, like an int or a
float. However, this kind of variable is special because of what it
stores. Instead of holding a direct value, it stores the address of
another variable in memory. When a pointer holds the address of a
specific location, it is said to be "pointing" to that location. Using
special symbols, we can access the data stored there.

Let's take a closer look at this.

int x = 10;
int* ptr = &x;

Here's what's happening:

x is an integer variable that holds the value 10
&x means "the address of x"
ptr is a pointer variable used to store the address of x
int* placed in front of ptr declares it as a pointer to an integer

Depending on the context, the * symbol can mean two different things.
In a declaration, like above, it indicates that a variable is a pointer.
In other contexts, it is used to dereference the pointer---that is, to
access the value stored at the memory address it points to.

In other words, it allows us to access x, like so:

std::cout << *ptr;

The line above prints the value 10. As you can see, by using the
pointer, we accessed and displayed the value stored in x.

What Are Pointers Used For

Pointers are used when you need direct control over memory or when
working with structures that rely on relationships between objects.

1. Dynamic Memory Allocation

int* p = new int(5);

This allocates memory similar to the earlier example, but with one
important difference. The keyword new allocates memory on the heap
(delete deallocates it). In this case, it allocates enough space to
hold an integer, places the value 5 into that memory, and assigns the
address to the pointer p.

After this statement executes, you have an integer stored on the heap
with the value 5, and p points to it.

Note that p is a pointer to an integer. This is necessary because it
must store the address of a memory location that holds an integer.

2. Working with Data Structures

Complex structures like lists, trees, and graphs all rely on pointers to
connect their nodes.

struct Node {
    int data;
    Node* next;
};

This segment of code defines what's known as a self-referential
structure. The pointer inside it---called next---can hold the memory
address of another Node. In other words, each node can point to
another node of the same type.

Without pointers like this, data structures such as linked lists and
binary search trees could not exist.

3. Interfacing with Low-Level Systems

Operating systems, embedded systems, and performance-critical
applications often require direct memory access and control. Pointers
provide that level of control.

A good example is game development, where performance and memory
efficiency are critical.

How Pointers Work (The Basics)

When you declare:

int x = 10;

The system stores the integer value 10 at some location in memory. For
the sake of illustration, let's say the address where this value is
stored is 0x1000.

Now, when you write:

int* ptr = &x;

This statement is saying: take the memory address of x and store it in
ptr. In other words, make ptr point to x. At this point, ptr
contains the value 0x1000.

When you dereference ptr using the * operator, you are accessing the
value stored at the memory address that ptr holds---in this case, the
value inside x.

*ptr = 20;

This statement does not change the pointer itself. It changes the value
at the memory location the pointer is referring to. In this example, it
replaces the 10 stored in x with 20.

Key distinction:

ptr by itself represents the address (for example, 0x1000)
*ptr represents the value stored at that address (the same value stored in x)

That distinction---between the address and the value at the
address---is the key to understanding how pointers work.

A Final Thought

Even though it may sometimes seem that way, there's nothing magical
about pointers. They are simply variables that can do very powerful
things. Keeping that in mind is half the battle.

That said, there are important things you need to pay close attention
to. You must be disciplined when working with raw pointers. Mistakes,
carelessness, or poor memory management can lead to undefined behavior.
There's a real sense of responsibility that comes with using these
variables---but that responsibility is also what makes them so powerful.

Understanding raw pointers means understanding how C++ really works.

And once you understand that, everything else in the language starts to
make more sense.

See Pointers in Practice

If you'd like to see pointers used in a real project, I use them
throughout my Binary Search Tree implementation. The repository includes
the full C++ source code, along with supporting documentation and an API
reference that walks through the design and behavior of the structure.

GitHub repository:

https://github.com/arto-b/BST_Demo

Understanding C++ Pointers: The Power Behind the Address

Arto Baltayan — Mon, 23 Feb 2026 22:40:10 +0000

Why Raw Pointers Still Matter

If you truly want to understand what's going on under the hood, you
need to understand raw pointers.

Knowing how to use pointers—and how memory is manipulated—isn't
just about syntax. It's about understanding the machine.

So that brings us to the question: what is a pointer?

Let's take a closer look at this.

int x = 10;
int* ptr = &x;

Here's what's happening:

x is an integer variable that holds the value 10
&x means "the address of x"
ptr is a pointer variable used to store the address of x
int* placed in front of ptr declares it as a pointer to an integer

Depending on the context, the * symbol can mean two different things.
In a declaration, like above, it indicates that a variable is a pointer.
In other contexts, it is used to dereference the pointer—that is, to
access the value stored at the memory address it points to.

In other words, it allows us to access x, like so:

std::cout << *ptr;

The line above prints the value 10. As you can see, by using the
pointer, we accessed and displayed the value stored in x.

What Are Pointers Used For

Pointers are used when you need direct control over memory or when
working with structures that rely on relationships between objects.

1. Dynamic Memory Allocation

int* p = new int(5);

After this statement executes, you have an integer stored on the heap
with the value 5, and p points to it.

Note that p is a pointer to an integer. This is necessary because it
must store the address of a memory location that holds an integer.

2. Working with Data Structures

Complex structures like lists, trees, and graphs all rely on pointers to
connect their nodes.

struct Node {
    int data;
    Node* next;
};

This segment of code defines what's known as a self-referential
structure. The pointer inside it—called next—can hold the memory
address of another Node. In other words, each node can point to
another node of the same type.

Without pointers like this, data structures such as linked lists and
binary search trees could not exist.

3. Interfacing with Low-Level Systems

Operating systems, embedded systems, and performance-critical
applications often require direct memory access and control. Pointers
provide that level of control.

A good example is game development, where performance and memory
efficiency are critical.

How Pointers Work (The Basics)

When you declare:

int x = 10;

The system stores the integer value 10 at some location in memory. For
the sake of illustration, let's say the address where this value is
stored is 0x1000.

Now, when you write:

int* ptr = &x;

This statement is saying: take the memory address of x and store it in
ptr. In other words, make ptr point to x. At this point, ptr
contains the value 0x1000.

When you dereference ptr using the * operator, you are accessing the
value stored at the memory address that ptr holds—in this case, the
value inside x.

*ptr = 20;

This statement does not change the pointer itself. It changes the value
at the memory location the pointer is referring to. In this example, it
replaces the 10 stored in x with 20.

Key distinction:

ptr by itself represents the address (for example, 0x1000)
*ptr represents the value stored at that address (the same value stored in x)

That distinction—between the address and the value at the
address—is the key to understanding how pointers work.

A Final Thought

Even though it may sometimes seem that way, there's nothing magical
about pointers. They are simply variables that can do very powerful
things. Keeping that in mind is half the battle.

That said, there are important things you need to pay close attention
to. You must be disciplined when working with raw pointers. Mistakes,
carelessness, or poor memory management can lead to undefined behavior.
There's a real sense of responsibility that comes with using these
variables—but that responsibility is also what makes them so powerful.

Understanding raw pointers means understanding how C++ really works.

And once you understand that, everything else in the language starts to
make more sense.

See Pointers in Practice

GitHub repository:

https://github.com/arto-b/BST_Demo

Why Documentation Fails in Engineering Teams

Arto Baltayan — Sat, 21 Feb 2026 23:51:03 +0000

Documentation doesn't fail because engineers don't like to write.
It fails because teams don't design for it.

Any engineer, manager, or CTO will agree: documentation is important. It
reduces bugs, speeds up development, lowers costs, protects
institutional knowledge, and clarifies code for new engineers—and for
those returning after a long hiatus.

Yet in team after team, documentation is outdated, incomplete,
inconsistent, or simply ignored. Despite good intentions and general
agreement about its value, it still breaks down. So what's actually
going wrong?

It's not a writing problem. It's a systems problem.

When documentation fails, it's rarely because someone couldn't write. It
fails because the environment around it wasn't designed to support it.

Let's explore what's really happening, why it keeps happening, and how
to fix it.

Documentation Without Ownership

The hill documentation dies on is easy to identify, but unfortunately
it's usually discovered too late in the project. The moment
documentation becomes everyone's responsibility is the moment it starts
to go wrong—and this happens, more often than not, at the very
beginning of the process.

When documentation is assigned to "the team," what this really means is
it belongs to no one. Everyone assumes somebody else is handling it.
They have their own responsibilities, and documentation becomes
secondary. That's the problem. A system where documentation is treated
like an afterthought is a system missing one of its key elements.

Without explicit ownership, documentation turns into a mishmash of
comments, guides, and API references—loosely assembled and rarely
effective. Eventually, most teams recognize something needs to change.
That's usually when a documentation engineer like myself is brought in.
By then, however, the damage has already been done.

Ownership doesn't just mean someone who writes comments. It means
someone accountable for structure, accuracy, and completeness. It means
someone responsible for asking difficult questions—and following
through once the answers surface.

Without that role, clear and reliable documentation is unlikely.

Documentation Is Part of the Infrastructure

Most engineering teams treat documentation as something you produce once
the project is complete. That kind of thinking almost guarantees it will
be rushed and incomplete. The real problem isn't effort—it's mindset.

Documentation is not output; it's infrastructure.

What does that mean? To answer that, we have to clearly define what
documentation actually is. It's not just sprinkling comments between
blocks of code. Documentation shapes how a system is understood and
used. It helps engineers support, build, and improve the architecture.
It guides customers toward adopting system features quickly and
efficiently.

For this to happen, documentation must be developed alongside the system
itself. Decisions aren't left to be hastily assembled at the end of the
project. Testing is where edge cases reveal themselves, and they should
be documented immediately while the context is still clear.

Infrastructure is continuously maintained. Documentation should be no
different.

Documentation Requires a System

Engineers optimize for what is visible. If something lives in their
workflow, they run with it. But as anyone who has worked in software
engineering knows, if it isn't made a priority, documentation rarely
stays in plain sight.

Documentation is not optional. It has to be integrated into the
workflow. This ensures it evolves alongside the software itself. When it
isn't, documentation drifts out of alignment with the code, and
inconsistencies begin to multiply.

Guilting engineers into writing more isn't the answer. The only way to
make documentation sustainable—and keep friction low—is to integrate
it into the same workflows and mechanisms used to produce code. It needs
to be reviewable, trackable, and measurable, just like the codebase
itself.

Engineers respond to systems. Documentation should function as a
subsystem within the larger engineering whole.

It's Not Writing—It's Design

Documentation is often treated as writing, not thinking. What does that
mean? Engineering teams tend to view documentation as a translation of
the code itself. Once the system is built, that's when the work of
describing it begins. Not so.

Good documentation isn't a transcription of code. It's a living,
evolving part of the system—and to reach its full potential, it must
include elements of design.

Here's what's interesting: when you set out to clearly explain a system,
inconsistencies start to surface. Writing an API reference can reveal
confusing abstractions. The act of documenting often exposes issues the
engineering team may never have confronted directly.

If documentation is delayed until after the project is complete, these
issues surface too late—or not at all. The architecture solidifies
before its flaws are revealed through explanation.

Documenting a system helps expose its vulnerabilities.

It may come as a surprise to some engineering teams that documenting a
system as it evolves leads to a stronger, more resilient codebase.

Rethinking Documentation

Here's a simple idea: we need to rethink how documentation is created in
most software engineering teams today. The problems are clear. Some
solutions exist. But what's really required is a shift in mindset.

We need to stop thinking about documentation as writing and start
thinking about it as code.

If documentation were treated the same way we treat code, it would be:

Designed
Written
Reviewed
Maintained
Versioned

Handled this way, documentation would improve over time and evolve
alongside the software.

And more importantly, it would actually be used—because it would be
built into the system, not bolted on afterward.

Just Ask - A Story About Growth as a Developer

Arto Baltayan — Sun, 07 Dec 2025 01:16:56 +0000

I've been coding for a long time. When I first started, I remember feeling such a profound sense of insecurity that it stopped me from ever asking for help—or even asking questions of any kind. It got so bad that it morphed into a fear of losing face, as if asking was somehow a violation of some unwritten coder’s code of honor.

Years later, after I had learned to suffer through my own problems in silence, something very unique and enlightening happened. I went to work as a computer science instructor at a local technical college. There, I met someone—another instructor—who I quickly became friends with.

Let’s call him Paul. Paul is probably the smartest man I know. His intelligence truly approaches the level of genius, and I’m not exaggerating. He was working on artificial intelligence systems 20 years before “AI” was even a buzzword. He went on to code the firmware inside pacemakers. Today, he's the Director of Research and Development at a major medical device corporation.

Anyway, our story begins in the lab at the technical college. My class was over, and I had my students in the lab working on an assignment or exercise I had given them. Next thing I know, Paul walks into the lab, comes straight up to me, and asks a question about a C++ statement he was planning to include in an assignment for his own students.

It wasn’t a hard question, but it was obscure enough that many coders wouldn’t know the answer. I just happened to know it. However, what truly astonished me wasn’t the question—it was the fact that he, of all people, didn’t know. Even more astonishing was that he came up and asked me. Wasn’t he embarrassed?

When I gave him the answer, I hesitated for a second, then decided to ask—because at that point in our friendship, I felt close enough to be candid.

“Paul,” I said, “I know what you were hung up on isn’t something that’s generally known... but weren’t you a little embarrassed to ask?”

He looked straight at me, and without missing a beat, said:

“If I don’t ask, how would I ever know the answer?”

At that moment, it was as if the heavens opened up and a light shone down on me. I felt so foolish. He was absolutely right.

What was truly life-changing was the realization that I had suffered through my career for so many years with a false sense of pride—one that could have been completely avoided. From that point on, I subscribed to my friend Paul’s way of coding and software engineering.

If you don’t know, why not ask? How else will you ever get better?

Sure, you’ll eventually figure things out on your own, but is it really worth putting yourself through all that? Especially when there are colleagues—many of whom are more than willing to help at a moment’s notice. That’s how we grow as developers and move on to bigger and brighter things.

It wasn’t until a couple of years later that I realized I wasn’t alone. Nearly every software engineer I encountered—whether novice or expert—struggled through their problems in silence, rarely asking for help or bouncing ideas off colleagues. And it hit me: this wasn’t just my issue. This was a cultural issue in our profession.

Fast forward several years. I’m working at a company, and one of my coworkers is a young firmware engineer. She had just accepted a new job and was about to move on. In her, I saw a little bit of myself—back when I was just starting out.

On her last day, I went to say goodbye and, before she left, I told her this little story about me and Paul from my earlier days as a developer. When I finished, her eyes lit up. I didn’t expect it to impact her the way it did—but why wouldn’t it? The experience had affected me quite drastically.

She told me she often felt the same way—apprehensive about asking for help. That sometimes, when she got stuck, she wanted to ask someone... but it felt embarrassing. She thanked me, and left.

It put a big smile on my face, because I knew I had changed the way she thought about software engineering—and perhaps the way she would move forward in her career.

I don’t know where this feeling of inadequacy or embarrassment comes from, but it has to stop. As software engineers, we put so much pressure on ourselves. We think we have to know everything—every nuance of every language, every protocol, every piece of technology that’s ever been developed since the dawn of the software age.

Not so.

If you’re stuck, ask—and see what happens. You’ll live a much happier, more productive life. And you wouldn’t believe how far that simple change can take you in your career.

That, I know for a fact.