DEV Community: Alexis Kypridemos

Structuring Technical Documentation by Date

Alexis Kypridemos — Thu, 12 Mar 2026 20:42:50 +0000

In technical documentation, we often speak of "structured content". I think this is a fancy way of saying "predictable" or "knowing what you're going to get", as opposed to free-form text.

Structured vs. unstructured content

To highlight the difference, compare a dictionary or phone book to a narrative book, for example, an instructional book on programming.

Entries in a dictionary or phone book are in alphabetical order, and are approximately of the same length.

In a narrative book, chapters or sections are far less uniform. Their length and scope can vary greatly. The chapters are arranged in an arbitrary order determined by the writer, which the reader may or may not find intuitive to navigate.

Structuring content presumably means making it more like dictionaries and less like narrative books.

Documentation frameworks and content types

Documentation frameworks such as DITA and Diataxis provide a set of predefined rules for structuring content.

What strikes me as odd about both frameworks is that they categorize content by type, such as concept, tutorial, reference, or explanation, an arbitrary dimension of little value to the reader. No one reads docs thinking, "I need a concept."

If the objective of structuring content is to make it predictable, I don't think either framework achieves this.

Alphabetical ordering

Alphabetical ordering would also not be meaningful. Most terms are product-specific and unknowable for new users, especially in software. You could place an entry for "content slice" under C, but new users wouldn't know where to look for it because they don't yet know what that is.

Reverse chronological ordering

With all that in mind, I'm leaning toward structuring documentation by date, sorted in reverse chronological order, like the news.

Across multiple software products, I've seen the same pattern in documentation: new features, delivered with a specific release on a specific date, and everything else. Let's call the latter behavioral notes.

I would put the new features at the top, sorted by date released, followed by the behavioral notes, sorted by date documented. The reason for the latter is that such items are often reported long after the behavior was first introduced, and that date becomes less important over time.

Conclusion

In conclusion, I'm proposing to structure documentation by date, a dimension readers already know and understand. It's hardly perfect, but less broken than arbitrary content types.

Good and Bad Navigation Patterns for Long HTML Pages

Alexis Kypridemos — Mon, 02 Mar 2026 18:15:06 +0000

Some HTML pages can run quite long. The longer the page, the more important clean, consistent navigation becomes.

Good Pattern

Link to the beginning of the table of contents at the end of each section

Example: https://codepen.io/Alexis-Kypridemos/pen/WbGQJmy

Why

It helps readers build a pattern. They know where to look for navigation. Also, if you're coding the HTML compiler or transformation, it's the easiest to implement.

Bad Patterns

1. Use CSS to create a paginated effect

All sections are hidden, except the one the reader selects from the table of contents.

Example: https://codepen.io/Alexis-Kypridemos/pen/PwGPaYO

Why

Too "magical" and brittle. For example, if you use the browser's "Copy Link to Highlight" functionality, the behavior can become unpredictable. For most cases, making all sections visible and scrollable, one after the other, is the cleaner option for both the reader and implementer.

2. Include links to the previous and next sections, where applicable, as well as to the table of contents

Example: https://codepen.io/Alexis-Kypridemos/pen/LERprpR

Why

It's too much. If all the content is on a single HTML page, the previous and next links are unnecessary and create visual "noise". Readers are likely to find it more intuitive to just scroll up and down.

3. When linking to the table of contents, link to the specific bullet point for that section

Example: https://codepen.io/Alexis-Kypridemos/pen/RNGWJRL

Why

You break the pattern. Each time a reader clicks a "Table of Contents" link, they get a slightly different result. Also, jumping to a specific bullet, for example the last one, obscures valuable context. The other contents might not be visible on screen, and the reader has to scroll up to view them. It's disorienting, even if momentarily.

Replace Broken Characters in Text Copied from Copilot Using PowerShell or Python

Alexis Kypridemos — Sat, 28 Feb 2026 23:47:06 +0000

You may have noticed the following:

If you copy text from a Copilot response by selecting it in your web browser and pressing Ctrl+C, the text carries over fine when you paste it. However, if you click the Copy message button instead, some of the characters, in particular single and double quotes, hyphens, and em-dashes, end up looking janky (mojibake).

Example of broken text:

I'm referring to the web-based chat UI, copilot.microsoft.com, not GitHub Copilot. I haven't tested this in the GitHub version.

I assumed it was a character-encoding issue; web browsers and most applications assume UTF-8 Unicode encoding nowadays, but perhaps Copilot was using some legacy Windows encoding like CP1252. But it seems to be more nuanced than that.

Here's Copilot's own explanation for why this happens:

It's almost always a Unicode normalization issue rather than a different encoding. The "Copy message" button tends to output characters like en-dashes, em-dashes, curly quotes, and non-breaking spaces in their full Unicode forms, while your browser's plain copy normalizes them to simpler ASCII-friendly equivalents.

Two patterns usually show up:

Smart punctuation: U+2013, U+2014, U+2018, U+2019, U+201C, U+201D.

Non-breaking spaces: U+00A0 or U+202F.

So I wrote some quick scripts to fix this.

The Fix

!!!Important: both scripts overwrite the original file.

Note: the script replaces em-dashes with - (a space, a regular hyphen, followed by another space). If you prefer something else, look for the line that replaces \u2014 and substitute it for your preferred logic.

Both versions of the script are meant to be run from the command line and expect a single argument, a path to a text file.

PowerShell

if (!$args[0]){
    write-host "Please provide a path to a TXT file."
    exit
}
$path = $args[0]
if (!(test-path $path)){
    write-host "Path $path does not exist"
    exit
}
try {
    $content = gc $path -encoding utf8
} catch {
    write-host "Could not read $path"
    exit
}
$content = $content -replace "\u2011", '-'
$content = $content -replace "\u2013", '-'
$content = $content -replace "\u2014", ' - '
$content = $content -replace "\u2018", "'"
$content = $content -replace "\u2019", "'"
$content = $content -replace "\u201C", '"'
$content = $content -replace "\u201D", '"'
set-content $path $content -encoding utf8

Python

#! /usr/bin/env python3

import sys, os, argparse

if __name__ == "__main__":
    if len(sys.argv) <= 1:
        print("Please provide a path to a TXT file.")
        sys.exit()
    path = sys.argv[1]
    if not os.path.exists(path):
        print("Path", path, "does not exist")
        sys.exit()
    try:
        with open(path, encoding='utf-8') as f:
            content = f.read()          
    except:
        print("Could not read", path)
        sys.exit()
    content = content.replace("\u2011", '-')
    content = content.replace("\u2013", '-')
    content = content.replace("\u2014", ' - ')
    content = content.replace("\u2018", "'")
    content = content.replace("\u2019", "'")
    content = content.replace("\u201C", '"')
    content = content.replace("\u201D", '"')
    with open(path, 'w', encoding='utf-8') as f:
        f.write(content)

Notes

For PowerShell:

This only works with -replace, not the string Replace() method.
The correct notation for referencing the Unicode characters is "\u2011" and not, for example, "`u2013" with a backtick (`), which is what Copilot originally suggested when I asked it to code this. (Incidentally, not to brag or anything, but neither script above is AI-generated.)

Copilot's response when I commented that it was leading me astray:

You're right on both counts:

In PowerShell, the correct escape form for a Unicode code point inside -replace is the string literal "\u2011".

The backtick form `u2011 only works in some contexts (mostly double-quoted strings), but not reliably inside .Replace() because .Replace() treats the string literally and doesn't interpret escape sequences.

So the reliable pattern is:
$text = $text -replace "\u2011", "-"
And yes - .Replace() does not interpret \uXXXX escapes at all, so it won't work there.

References

A similar PowerShell script. It uses [char]0x2013 notation which may or may not work, I'd need to try it:
https://www.linkedin.com/posts/kyle-jones-312b17185_having-issues-with-unicode-characters-in-activity-7398192899500326914-fGQM/

This is where I found the correct notation for Unicode characters in PowerShell:
https://serverfault.com/questions/313695/powershell-2-how-to-strip-a-specific-character-from-a-body-of-ascii-text

This helped to figure out which Unicode code points correspond to which characters:
https://decodeunicode.org/en/u+2012

Sort Items in a Directory by Descending Size Using Python, PowerShell, C#, or Go

Alexis Kypridemos — Tue, 05 Nov 2024 21:47:01 +0000

A simple program to sort all the items in a directory, be they file or folder, by descending size.

Sorting items in a directory by descending size is not as straightforward as you might think, whether you are using a graphical file browser or the command line, because operating systems do not calculate the total size of a directory's contents when browsing a directory tree. This article offers complete working programs to overcome this on most operating systems.

Problem

Perhaps you will find the following familiar:

Whether for work or for personal projects, I like to organize my digital assets by creating a parent directory, let's say one called Projects, and storing all the content for the individual projects in there. If a project is small and doesn't involve a lot of content, I'll use a single file, usually a text file. If a project involves more content, say a text file as well as a couple of screenshots, I'll create a folder for that project and place all the related assets in there. So, from my perspective, the single text file and the folder are equivalent in the sense that each represents a project. The only difference is that the folder represents a bigger project, one with more stuff.

Sometimes I want to see which of my projects is currently the largest, which has the most stuff. This usually happens because I haven't worked on a particular area for some time, so when I come back to it, I want to see which project has the most content. My reasoning being that the project with the most content should be the most complete, and therefore probably the one I should start working on first, as it will be easiest to finish.

For example, consider a directory with the following contents:

Name	Type	Size
Huge Project.txt	File	2.6KB
Larger Project	Folder	1.07KB
0 - Tiny Project	Folder	0KB
Basic Project.txt	File	0.36KB
Big Project.txt	File	2.11KB

Sorting the above directory by descending size should output:

Huge Project.txt        2.6KB
Big Project.txt         2.11KB
Larger Project          1.07KB
Basic Project.txt       0.36KB
0 - Tiny Project        0KB

However, this is not what we get when we click the Size column header in graphical file browsers on Windows, Mac, and Linux.

Windows

Windows File Explorer - The files are sorted by descending size, and the folders are displayed underneath, in ascending alphabetical order.

Mac

MacOS Finder - The directory contents are sorted the same as on Windows.

Linux

Linux (Ubuntu) Files app - The folders and files are sorted correctly, but individually; folders first, then files. So the item that appears first on the list is not actually the largest item in the directory.

Using the command line provides output that is somewhat closer to the desired one, but still not entirely correct:

Windows

On Windows, we can use the good, old dir command with the /b (bare format, essentially the item full path only minus details we don't need) and /o (order by) flags. We can set the /o flag to -s. The s is for size. When ordering by size, the default behavior is to order by smallest to largest, so we prefix s with - to reverse the order, largest to smallest.

dir /b /o:-s

Output:

Larger Project
0 - Tiny Project
Huge Project.txt
Big Project.txt
Basic Project.txt

Mac and Linux

There are various command combinations for directory content sorting on UNIX-based systems such as Mac and Linux. Most involve using du, sort, and ls. Other examples I found online threw find and grep into the mix as well.

Here are the ones I tried:

du | sort

du -a -h --max-depth=1 | sort -hr

Output:

32K     .
8.0K    ./Larger Project
8.0K    ./0 - Tiny Project
4.0K    ./Huge Project.txt
4.0K    ./Big Project.txt
4.0K    ./Basic Project.txt

ls

Using the -S switch on the ls command is supposed to do exactly what I'm looking for, sort items by descending size.

ls -S

Output:

'0 - Tiny Project'  'Larger Project'  'Huge Project.txt'  'A - Big Project.txt'  'Basic Project.txt'

The output is still off. I tried adding the -l (long) switch.

ls -lS

Output:

total 20
drwx---r-x 2 admin admin 4096 Sep 20 21:49 '0 - Tiny Project'
drwx---r-x 2 admin admin 4096 Sep 20 21:49 'Larger Project'
-rw-rw-r-- 1 admin admin 2667 Sep 20 21:49 'Huge Project.txt'
-rw-rw-r-- 1 admin admin 2164 Sep 20 21:49 'Big Project.txt'
-rw-rw-r-- 1 admin admin  368 Sep 20 21:49 'Basic Project.txt'

The output includes more detail, as expected, but the sort order is the same as before.

Root Cause

While the output of the various commands does not provide the desired output, it does highlight the root cause of the problem. When browsing a directory tree, operating systems do not recurse into folders to calculate the total size of their contents. Instead, they treat all folders as having the same fixed size. Usually this is the file system's minimum block size, commonly 4096 bytes, 4KB.

Solution

There must be at least a dozen free tools out there that solve this problem, but to be honest, I didn't even look. Writing a script/program that does the same thing and then sharing it here felt like it would be easier, involve less bloat, hopefully useful for others, and definitely more fun.

I've waffled on long enough. Here is the code:

Python

#! /usr/bin/env python3

import sys, os, argparse

def get_dir_items(path):
    results = {}
    items = os.scandir(path)
    for item in items:
        if item.is_file():
            results[item.name] = item.stat().st_size
        elif item.is_dir():
            dir_size = 0
            dir_results = get_dir_items(item.path)
            for key, value in dir_results.items():
                dir_size += value
            results[item.name] = dir_size
    return results

if __name__ == "__main__":
    if len(sys.argv) <= 1:
        print("Specify a path as the first argument.")
    else:
        root_path = sys.argv[1]
        if not os.path.exists(root_path):
            print(root_path, "is not a valid path")
        else:
            results = get_dir_items(root_path)
            results_sorted = dict(sorted(results.items(), key = lambda item: item[1], reverse = True))
            for key, value in results_sorted.items():
                print(key, "\t", round(value / 1024, 2), "KB")

PowerShell

if (!$args[0]){
    echo "Specify a path as the first argument."
} else {
    $root_path = $args[0]
    if (!(test-path $root_path)){
        echo ($root_path + " is not a valid path")
    } else {
        $results = @{}
        $items = gci $root_path
        foreach($item in $items){
            if ($item -is [System.IO.DirectoryInfo]){
                $results[$item.Name] = (gci $item.FullName -recurse | measure length -sum).Sum
            } else {
                $results[$item.Name] = $item.Length
            }
        }
        $results_sorted = $results.GetEnumerator() | sort value -descending
        foreach($result in $results_sorted){
            echo ($result.Name + "`t" + [math]::Round(($result.Value/1024), 2) + "KB")
        }
    }
}

C Sharp

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
namespace Program {
    class Program {

        private static Dictionary<string, long> getDirItems(string path) {
            Dictionary<string, long> results = new Dictionary<string, long>();
            DirectoryInfo directoryInfo = new DirectoryInfo(path);
            FileInfo[] files = directoryInfo.GetFiles();
            foreach(FileInfo file in files){
                results.Add(file.Name, file.Length);
            }
            DirectoryInfo[] directories = directoryInfo.GetDirectories();
            foreach(DirectoryInfo directory in directories){
                var dirResults = getDirItems(directory.FullName);
                long dirSize = 0;
                foreach(var dirResult in dirResults){
                    dirSize += dirResult.Value;
                }
                results.Add(directory.Name, dirSize);
            }
            return results;
        }

        static void Main (string[] args) {
            if (args.Length < 1){
                Console.WriteLine("Specify a path as the first argument.");
            } else {
                string rootPath = args[0];
                if (!Directory.Exists(rootPath)){
                    Console.WriteLine("{0} is not a valid path", rootPath);
                } else {
                    var results = getDirItems(rootPath);
                    var resultsSorted = results.OrderByDescending(x => x.Value).ToDictionary(x => x.Key, x => x.Value);
                    foreach(var result in resultsSorted){
                        Console.WriteLine("{0}\t{1}KB", Path.GetFileName(result.Key), Math.Round((decimal)result.Value / 1024, 2));
                    }
                }
            }
        }
    }
}

Go

package main

import(
    "fmt"
    "os"
    "path/filepath"
    "sort"
)

func getDirItems(path string) map[string]int64 {
    results := make(map[string]int64)
    items, e1 := os.ReadDir(path)
    if e1 != nil {
        fmt.Println("Error:", e1)
        os.Exit(1)
    }
    for _, item := range items {
        if item.IsDir(){
            var dirSize int64 = 0
            var dirResults = getDirItems(filepath.Join(path, item.Name()))
            for _, dirResult := range dirResults {
                dirSize += dirResult
            }
            results[item.Name()] = dirSize          
        } else {
            itemInfo, e2 := item.Info()
            if e2 != nil {
                fmt.Println("Error:", e2)
                os.Exit(1)
            }
            results[item.Name()] = itemInfo.Size()
        }
    }
    return results
}

func main(){
    if len(os.Args) < 2 {
        fmt.Println("Specify a path as the first argument.")
    } else {
        rootPath := os.Args[1]
        _, e1 := os.Stat(rootPath)
        if e1 != nil {
            fmt.Println(rootPath, "is not a valid path")
        } else {
            results := getDirItems(rootPath)
            var resultKeys []string
            for key, _ := range results {
                resultKeys = append(resultKeys, key)
            }
            sort.Slice(resultKeys, func(i, j int) bool{
                return results[resultKeys[i]] > results[resultKeys[j]]
            })
            for _, key := range resultKeys {
                fmt.Printf("%s\t%.2fKB\n", key, float64(float64(results[key]) / 1024))
            }
        }
    }
}

There are some minor differences between the four implementations, but the general approach used for all four is the same:

Create a recursive function that returns a collection of key-value pairs of item (file or folder) name and size.
In the main function or block, do some basic input validation, and if the user has provided a valid path, run the recursive function on that path.
Sort the output of the recursive function by value (size), in descending order.
Print the sorted output to the console. Each line printed adheres to the format: the item name, followed by a tab character, followed by the item size divided by 1024 and rounded to two decimal places to get the size in kilobytes, followed by "KB" to denote the size unit.

Usage

On the command line, pass the path to the directory you want to sort as the first parameter. I won't list all the possible examples, but here are a couple, assuming you've copied the code and saved it as a file named dir_desc, short for "directory descending", plus the appropriate file extension:

Using Python on Mac or Linux:

python3 dir_desc.py <some path>

Using PowerShell on Windows:

powershell -f dir_desc.ps1 <some path>

Differences Between Languages and Implementations

Python and Go resemble C and other C-like languages in that the first command line argument is the second item in the args array. In the .NET languages, PowerShell and C#, the first argument is the first item in the args array.
In PowerShell, there is no need to create a separate recursive function, because the desired result can be more easily achieved by using the built-in Get-ChildItem (gci) and Measure-Object (measure) cmdlets.
In Go, sorting a collection of key-value pairs (map) by value requires a couple more lines of code than in other languages, as the built-in sorting functions are designed to work with arrays/slices, not maps.
In Go, rounding a floating point number to X decimal places is handled when printing the output, using the fmt.Printf() function, as opposed to using a function like, say, math.Round() (which wouldn't do what we want anyway, as it rounds to the nearest integer). If you have a C background, this is probably intuitive. For the rest of us, it's a bit bizarre, but works fine.

I ported my original approach in Python to a few other languages, so that there is at least one version that should work on each of the three major operating systems:

Mac and Linux: should have the python3 interpreter installed by default. If not, you can use the Go version. Some Linux systems may have a version of gcc installed by default that can compile Go, but most systems will not, so you will need to download the Go compiler.
Windows: the PowerShell version should work out of the box on systems with Windows 10 or later. For older systems, the C# version is probably the better choice. You can use Windows' built-in C# compiler to compile the code.

And that's it. Another yak, shaved. I hope you found this useful.