What's up doc?

I implore you. As a developer for over 25 years.

Document it. It needs to be documented.

Make a journal. 📓 Crochet it. 🧶 Etch it on stone tablets. 🪨 Get a tattoo. 💘

Just do it.

Your future self or the poor developers you left behind to manage your code will thank you for it.

Fear of not sounding “official”

This is often the first hurdle, definitely with myself. A fear that your personal writing style just isn’t great. It doesn’t matter. Just start #$*& writing it down. Pretend you’re writing a message to a friend. Don’t worry about your content sounding like a polished publication on a company website. Get. it. on. paper!

Just start with a text file and go from there.

Here are the key things to consider as you start.

Documentation should be structured

Within each entry, a consistent structure should be applied. A good starting point are these components.

Title, Author, Date, Categories, Summary, Body

Create a template for your entries so you don’t have to start from scratch. You can even create shortcuts like a VS Code snippet to assist in filling it out. Here’s one I built for this blog, which uses Jekyll templating. I just type “post” and tab and bam! On my way. See the end of the post to grab the code.

Documentation should be exportable

The structure and storage of the documentation should allow you to easily transition the content to different formats. Markdown is especially good here, and easily understandable for even non-technical individuals.

Documentation should be searchable.

Find a way to make your documentation searchable. That doesn’t necessarilly mean pushing them into sharepoint, a wiki, etc. A good example - Notepad++ has excellent search options. You can search an entire directory structure using wildcards or even regex and immediately jump to the lines that have matches. As you documentation grows you can find new ways to index the contents, and the structure you added will make that move much simpler.

Documentation should be preserved at all costs.

I can’t stress this enough! All documentation is worthwhile. Someone wrote it down, it has meaning. Preserve what you can, creating a little structure with it if there is none (add a summary, date and categories for example). My team recently ran across an situation where we had to ressurect a VB.NET Forms application that was built in 2005. Because we had saved the documentation and the code (archived repository in git) we were able to brush it off and get it up and running much faster than we would have without it!

Go write something!

Related Links

• Writing Documentation in VS Code
• Structuring your Technical Documentation
• Inspiration from Start a F*ing Blog
• How to create a VS Code snippet

Jekyll Template VS Code Snippet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "jekyll-template-post": {
	"isFileTemplate": true,
    "prefix": ["post", "post-template"],
    "body": ["---", 
		"layout:     ${1|post,page,default,none|}", 
		"title:      ${2}", 
		"date:       $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND", 
		"summary:    ${3}", 
		"categories: ${4|fediverse,dotnet,leadership,mastodon,indieweb,blazor|}", 
		"thumbnail: ${5|fa-pen-to-square,fa-radio,fa-face-tired,fa-fire|} #https://fontawesome.com/search?o=r&m=free", 
		"image: /assets/img/posts/$CURRENT_YEAR$CURRENT_MONTH$CURRENT_DATE$CURRENT_HOUR$CURRENT_MINUTE.png #if no image use default_card_png",
		"${7|spotify_playlist,mastodon_post_url|}: ${8} #0hKSSg9Er6Ez1V9Ec34ics or https://mastodon.social/@box464/109650202481794162",
		"tags:",
		" - ${9}",
		"---"],
    "description": "A template structure for a new post in jekyll markdown format."
  }
}