DEV Community: Nassbin

📘 Adopting a Documentation Framework: A Practical Guide for Tech Teams

Nassbin — Fri, 09 Jan 2026 08:24:20 +0000

Introduction

Technical documentation is more than a set of Markdown files — it is a strategic asset. Good documentation preserves knowledge, accelerates onboarding, reduces risks, and supports overall technical quality. Yet in many organizations, documentation exists… without truly living. It becomes outdated, unused, or inconsistent.

This article proposes a clear, operational, and reusable plan for establishing a lasting documentation framework.

1. Why Adopt a Documentation Framework?

Without structure and clear ownership, documentation naturally drifts into irrelevance. A formal documentation framework ensures that:

each document is useful and reader-focused,
ownership is clearly assigned,
a consistent writing style is maintained,
documentation is treated like code: versioned, reviewed, validated.

In short: documentation becomes a product, not an afterthought.

2. Goals of the Documentation Framework

2.1 User-Centered Documentation

Every document must be designed for a well-defined audience:

internal developers,
QA, DevOps, architects,
external partners,
integrators or non-technical stakeholders.

Tone, depth, and examples should be tailored to these readers.

2.2 Write Documentation Alongside Development

Documentation should be produced as work happens, not after the fact. It must capture:

technical decisions,
non-obvious behaviors,
architectural constraints,
discovered pitfalls or ambiguities.

Writing early → writing accurately.

2.3 Transparency and Clarity

Anything that is not obvious should be explained, including:

architectural choices,
trade-offs,
complex domain concepts,
known limitations.

Documentation should reduce uncertainty, not increase it.

3. Use the Diátaxis Documentation Model

The Diátaxis model is a modern and widely adopted framework for structuring technical documentation. It categorizes documents into four complementary types:

Tutorials — step-by-step learning for beginners
How-To Guides — targeted problem-solving steps
Reference — factual information (APIs, schema, parameters)
Explanation — conceptual, contextual, high-level knowledge

Each new document should fit into one of these categories to ensure:

intuitive structure,
consistent organization,
predictable navigation.

The Diátaxis Compass helps authors choose the correct type.

4. Recommended Document Structure

An effective document follows a hierarchy from the most essential to the most specific:

Summary / Objective
Target Audience
Quick Start (for external or on-boarding readers)
Primary Use Cases
Key Considerations
Examples (simple → advanced)
Related Resources
Glossary & Acronyms

This structure helps readers quickly find what they need.

5. Style & Quality Guidelines

A good documentation framework ensures uniformity and readability.

🧭 Recommended Style Guidelines

Use clear, simple English.
Prefer short sentences and concrete examples.
Define all acronyms (or link to the glossary).
Minimize screenshots (they break easily as the UI evolves).
Use text-based diagrams (e.g., PlantUML) when possible.
Highlight critical information.
Maintain consistent navigation and structure.
Enforce a file-naming convention.
Split documents when they become too large.

🛠️ Recommended Quality Tools

Vale — a prose linter to enforce style rules.
Documentation CI/CD — link checking, validation, automated diagram generation.
Established editorial guidelines from:
- Google
- Microsoft
- Red Hat

These ensure long-term consistency across contributors.

6. Templates & Processes

To maintain long-term coherence, teams need:

official templates for each Diátaxis document type,
a documentation onboarding guide,
a structured review workflow,
a centralized glossary driven by a recognized system (e.g., The Good Docs Project Terminology System).

The templates from The Good Docs Project are a strong and reliable foundation.

7. Implementation Plan

To successfully introduce a documentation framework, follow these steps:

Define the documentation types to adopt.
Create and distribute official templates.
Set up documentation CI/CD checks.
Build and maintain a unified glossary.
Define an on-boarding workflow for new contributors.
Establish a formal documentation review policy.

This transforms documentation into a structured, living ecosystem.

8. Managing Assets: Images, Diagrams & External Resources

To avoid broken or unmaintainable documents:

Never embed externally hosted images → store them locally.
Always commit source files for diagrams (e.g., .drawio, .puml).
Document build or export steps when relevant.

This guarantees future-proofing and ease of updates.

Limits & Considerations

Formalizing documentation raises key organizational questions:

✔ Definition of Done

Is a task truly “done” if it isn’t documented?

✔ Measuring Documentation Quality

Are people actually using the documentation?

✔ Resourcing

Documentation requires time, tools, and training — this must be acknowledged and supported.

Conclusion

A structured documentation framework is not bureaucratic overhead. It is a strategic investment that improves:

technical resilience,
development speed,
on boarding efficiency,
knowledge continuity.

By adopting a model like Diátaxis, defining templates, enforcing a consistent style, and integrating documentation into CI/CD, organizations can turn documentation from a fragile necessity into a scalable, reliable operational asset.

Enhancing JavaScript Code: Using Objects Instead of Switch Statements

Nassbin — Tue, 14 Jan 2025 07:59:28 +0000

Introduction

This is a short and somewhat unusual topic to write about, but I haven’t encountered it much on the web while working, so here is my contribution. I would love to hear people’s opinions on this method since I use it regularly. I don’t like writing multiple cases inside a switch statement, so I found using an object to be a cleaner alternative. It may not be faster, but the code looks cleaner to me.

Demonstration

I want to handle orders with different payment statuses and apply different treatments depending on whether they are paid or not.

Let's begin with this:

const orders = [{
  "id": 1,
  "product": "shoes",
  "paymentStatus": "Paid"
},{
  "id": 2,
  "product": "pants",
  "paymentStatus": "Pending"
},{
  "id": 3,
  "product": "tie",
  "paymentStatus": "UnPaid"
}];


const handlePaymentStatus =(order) =>{
  return order.paymentStatus
}

for (const order of orders) {
 handlePaymentStatus(order)
}

We want to apply a specific treatment based on the order.paymentStatus. A simple solution would be to use a switch statement like this:

let orders = [{
  "id": 1,
  "product": "shoes",
  "paymentStatus": "Paid"
},{
  "id": 2,
  "product": "pants",
  "paymentStatus": "Pending"
},{
  "id": 3,
  "product": "tie",
  "paymentStatus": "Unpaid"
}];


const handlePaymentStatus =(order) =>{
switch (order.paymentStatus) {
  case 'Paid':
    console.log("it's all good");
    break;
  case 'Unpaid':
    console.log("need to be paid");
    break;
  default:
    console.log(`We'll wait`);
}
}

for (const order of orders) {
 handlePaymentStatus(order)
}

It's a simple case since we have two options and a default, but imagine it with multiple payment methods. We’ll keep it like this for the purpose of clarity:

let orders = [{
  "id": 1,
  "product": "shoes",
  "paymentStatus": "Paid"
},{
  "id": 3,
  "product": "tie",
  "paymentStatus": "Unpaid"
},{
  "id": 2,
  "product": "pants",
  "paymentStatus": "Pending"
},];

const paymentStatusHandlers = {
  'Paid': () =>  console.log("it's all good"),
  'Unpaid': () => console.log("needs to be paid"),
}

for (const order of orders) {
 paymentStatusHandlers[order.paymentStatus] 
    ? paymentStatusHandlers[order.paymentStatus]()
    : console.log("We'll wait")
}

Conclusion

Using an object instead of a switch statement can make your code more readable and maintainable, especially when dealing with multiple cases. It’s a matter of personal preference, but it’s worth considering as an alternative approach.

Feel free to let me know if there are any other specific changes or additions you'd like to make!

Vue 3 - Recursion with Treeview component

Nassbin — Tue, 07 May 2024 12:50:35 +0000

Hi welcome back to my Vue series where I share intermediate tips and tricks to use in order to create a view components.

Today, we will focus on building a Treeview Component.

Which looks somewhat like this:

They are very useful il many cases and exists in many different shapes and forms (pun intended). One of my colleague (s/o P.A ) came across the challenge of implementing it using recursion. I am not a stranger to this principle but I never thought about using it through Vue 3. It's a rather useful techniques which forces you to make your component extremely robust because he will call himself and avoid code duplication.

Our Goal

We will do a file explorer which is the most basic application for a Treeview maybe in the whole history of computer. There is lots of different ways in which you can implement it but we are going to see it through recursion.

Coding it

I will try to maintain all of the code of my vue serie inside of this repository. Just switch to the according branch.

Object Structure

We will have a very basic object structure like this:

const fileStructure = {
  name: "src",
  type: "folder",
  children: [
    {
      name: "components",
      type: "folder",
      children: [
        {
          name: "TreeItem.vue",
          type: "file",
        },
        {
          name: "Treeview.vue",
          type: "file",
        },
      ],
    },
    {
      name: "App.vue",
      type: "file",
    },
  ],
};

I have used the basic file structure of our project kind of a structureception if you like.

An Item will have a name which allow it it to identify it and it's unique juste like in a real file explorer. then a type to ensure what we are working with but you could take another approach. We could instead says that if an item doesn't have any children attribute it's a file but this won't cover the empty folders uses cases.

Finally the children attributes that allows us to make the recursion possible.

Treeview Component

<script setup>
defineProps(["fileStructure"]);
</script>

<template>
<ul>
  <li v-for="child in fileStructure.children" :key="child.name">
    <span>{{ child.name }}</span>
    <input type="checkbox" >
    <Treeview v-if="child.type === 'folder'" :fileStructure="child" />
  </li>
</ul>
</template>

This all the code there is to it in order to display our treeview. Notice how simple and concise it is. We define our fileStructure we loop on the children and if the type is folder we call our Component. Since our nested object have the same consistent shape we can call it like this.

Selection

To demonstrate how it simple we will implements selection via a checkbox input juste like this:

<script setup>
defineProps(["fileStructure"]);
const model = defineModel();
function addFileOrFolder(child) {
  if(model.value.includes(child)){
    model.value = model.value.filter((file) => file !== child);
    return;
  }
  model.value =[...model.value , child];
}
</script>

<template>
<ul>
  <li v-for="child in fileStructure.children" :key="child.name">
    <span>{{ child.name }}</span>
    <input type="checkbox" @change="addFileOrFolder(child.name)" >
    <Treeview v-if="child.type === 'folder'" :fileStructure="child" v-model="model" />
  </li>
</ul>
</template>

The same way we call the v-model recursively and add no complexity added. This a voluntary simple example. This acts as a blueprint for more complex system like getting the filepath.

Conclusion

Thanks for reading this far I hope this will give your inspiration for components implementation. See you next time!