Documentation Tips ​

Introduction ​

I hate documenting, I hate writing, while we're at it I hate mondays and my alarm clock... and yet here we are!

However documenting is an essential part of a technical role, it allows us to convey intent, instruction as well as understanding to a user or co-worker.

So this page contains my top tips and tools which I use for writing!

Writing ​

1. Keep writing

Its a tech blog, I am fortuante to be in a tech role. So I've started the habit of keeping notes while working on something new, or even solving a problem. Even if it isn't something published it's always something that can be referenced.

Currently I'm hiding out in my office waiting for my new role to start in 8 days time, with my wifes long list of house todos and 2 seasons of Vikings to watch I'm limited for time! Despite not having anything new and shiney to work on, coming off an exciting Azure ML project but sadly decided to move on.
I will aim to commit to forming a habbit, by working an hour a day towards a post or course. The timespent will be in either writing, learning or implementing something with hopes of brining it to this site.

2. Don't hide behind jargon

"If you want to master something teach it." - Richard Feynman

We can't teach someone by confusing them!

Documents are meant to be useful as well as readable.
Jargon often leads to over complicated documents, which will put off those who don't really have a clue what you're talking about. In a years time that can also include the writer themselves!

It is sometimes needed, but if flaunted about too frequently it's often in an attempt to either show off or hide lack of true understanding.
The same can also be said for meetings, where jargon can lead to confusion, at best. At worst can lead to a team following someone blindly who didn't even understand their own sentance, but used big words and now we're 1/2 way into our sprint not knowing why we went down this route. (Yes I've been there, yes I may have been the blind man leading)...

Keep it clear, cohesive and concise (Something I'm struggling with).

3. Break up the writing

Look to incorporate diagrams to either replace text or to make you're writing more understandable.
Don't do what I do which is throwing gifs in left, right and centre!

4. Edit

Once you've written your page, re-read the masterpiece to make sure everything is sound. If it doesn't help you or the reader, bin it!
Take time to also have a bit of fun with it - elaborate your notes within the post, inject some personality into it and away we go.

Once you've read it through and are happy, publish it and never look back (unless someone including yourself has feedback, corrections or hates it).

Actually this is a lie, always look back dust off your old documents, and see how you can add to or improve. You also want to remember what's covered, much like code you don't want to repeat yourself.

Tools ​

Notes ​

I currently use obsidian for my day to day note taking, it's quick easy to use and is apparently my second brain.... so why wouldn't I use it.
For personal use it is completely free, there are tonnes of community plugins, key one's I use are mindmap visualisers, kanban boards and spell check. For me it just makes note taking and document linking a lot easier.
I'm sure there are other powerfull plugins I could be using, but the templating and the fact it's in markdown, easily transferrable to this blog is a no brainer.

I mean I could just publish this blog using obsidian, but I enjoy using a variety of tools to make my life harder.

Diagrams ​

I should say draw.io, but I'm embarrassed to say I've used, and still use visio 🫣 I've been predominately within the Azure space for the past 3 years so it just makes sense.

But to make docs and presentations more fun I've been leaning towards excalidraw. It just gives the whole diagram a sketchy, hand drawn look which I can't help but feel drawn to - I mean it just looks awesome!

Blog ​

Vitepress is in alpha, so don't use unless you're willing to keep up with potentially breaking changes, but it's extremely lightweight, whilst still allowing the use of vue components.

If you would like to follow suit, I've written a how to in the previous page

Conclusion ​

Thats it for now! I'll look to keep this document up to date as I find new and exciting things to share!