Does extensive documentation do more harm than good?
Tags: opensource, showdev, discuss, github
Published: 2022-01-03 00:01:33

I feel like I tend to write too much documentation in code, PR descriptions, PR comments, JIRA tickets, markdown files, etc. If I can write documentation on it, then you bet that I am doing it :laughing: There are few exceptions where I don't write documentation such as self-explanatory, 1-liner code... I think I do it because I don't like people asking questions. Really anti-social behavior :blush: Some may say that I have obsessive-compulsive disorder. 

**Warning! The following GIFs may cause siezures as they have been sped up to meet maximum file size limits.** 

I'm writing documentation in code, extensively...

![Documentation in code](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8f3gy12swysxj9gf5ku7.gif)

> Useful? Not useful? Who cares? No one? Readable? Beautiful?

I'm writing howto pages for all APIs, functions, and entities in the library...

![Markdown Howto pages](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/khxzf7p83di0ll36324v.gif)

> Cool? Or insane? Or cool but a waste of time? 

It looks like this in the mobile GitHub app...

![GitHub app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hg6vzue9za1xjwyyz83p.gif)

> Tell me it's not pretty... Tell me! (Please don't tell me).

I'm using GitHub Pages as a free website for my hard work on my documentation...

![Html Howto pages](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3pnnr5vmc2vi4twwu481.gif)

> Can't really turn down a free domain and 1-click theme changes :smile:

I'm writing really long responses in my open source discussion pages, issues, and PRs...

![Issues and PRs](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oiwo99bdj2jgs5tirowv.gif)

> Because I want to make my collaborators feel heard and appreciated. 

These insane tendencies carry over to my professional life. I write really thorough, detailed JIRA tickets, Slack messages, architectural docs, engineering notes, to a point of insanity. Typically, when I post my response to people at work, they usually don't have any follow up questions. They expect that if they ask Vandolf a question, he will answer that question and give every bit of context related to it with links to supporting documents and visual aid (GIFs and videos with callouts) when needed. It is probably starting to annoy some people at work despite them publicly giving me praise for it.

> I don't have a GIF for this part because I don't want to get fired :fire:

It also carries over to my personal life, which I will not discuss here...

So... Lately, I've been wondering if I'm wasting time being so... thorough and a bit of a perfectionist. I spend more time documenting than actually writing code. I guess it reduces the [bus factor](https://en.wikipedia.org/wiki/Bus_factor) and at the same time makes me super dispensable because everything I know is documented. So they can just fire me and let someone else take the lead :grin: The upside to all of this is that I am able to completely disconnect from work. I can completely discard all work-related thought (may that be private or open source) because I know that when I resume, I would not have lost any context due to my poor memory.

## Thoughts?

DO I HAVE A PROBLEM? Is something wrong with me? Am I trying too hard? Being too anal? Should I calm down? Relax? Find something better to do? Why am I even doing all of this? Is there such a thing as too much documentation? Do people even read documentation? How do you interact with people like me? Is it tiring for you? Does it make you not want to talk to me because then you will feel committed to reading a blog as a response to every single one of your questions?