Day 1: The Art of Writing - DevOps FullStack Secrets

Writing is an integral important part of what we do in the world and more so in the complex DevOps or Full Stack Development world. Indifferent if you’re a software engineer writing code or a devops engineer writing bash or terraform automation scripts. Writing is a form of communication we need on a daily basis; Be it emails, documentation, executive summaries for management or explaining ideas to non technical customers . As any skill, writing improves with practice.

Writing is Thinking

Writing is thinking and writing WILL help you organize your thoughts and ideas. And writing helps us organize our memory. There’s ample research stating that writing IS one of the best psychotherapy emotional processing tool out there ¹ I know there’s a preconception of programmers and IT people being introverted and lacking intrapersonal communication skills. It doesn’t have to be that way. As you’ve mastered your craft, you too can master the art of communication.

Make your work visible

Most of the tech work we do is invisible and unknown to others (managers, colleagues, etc). Writing about it helps us document the steps we’ve taken. Writing improves our retention and understanding. It will also give you a chance to explain WHY an idea is good or bad. If you’re like me you may solve tens to hundreds of different problems a day. I used to document only the most complex problems. It’s very liberating when we can go back to our notes on a daily basis for things we’ve solved before or just to review ideas and solutions. In reality, we should aim to document anything which takes more than 5 minutes to solve. Taking time to document and write down the problems you had and how you solved them. Your our future self will thank you. And so will other people, How do you think the internet works?

Brain Overload - Second Brain

We can’t store everything in our brain. This is why it’s much more important to be able to solve a problem and know how to solve it than to learn a manual entry by heart but being unable to use it.

Afraid of sharing your writing thinking that it’s not that good? No need for perfection. 3 steps to success

1. just write everything down as in a brain dump without worrying about grammar, logic, order. Just write what comes to your mind ignoring your critical self. Keep it in a draft, and come back later.
2. Read it, edit it and iterate as many times a you want. THe more you EDIT the better it becomes and the more you will train yourself to remove excess. You will probably write 3 A4 pages and summarize it down to 1 A4 page.
3. Don’t use AI unless you want to brainstorm or want to gather intel on how to present an idea to stakeholders. Always use your OWN brain and thoughts. Instead of externalizing your thinking, you build valuable skills. Become irreplaceable.

Do the above steps even if you never publish anything and decide to keep your documentation local.

Book Recommendations

I’d recommend reading 3 distinct books to get an idea of how to actually get things done by taking notes. You may also want to take hand notes instead of going 100% in the technology route;). Your hand brain pathways will thank you.

• Bullet journal method by Ryder Carroll
• How to take smart notes by Sonke Ahrens
• GTD getting things done by David Allen

Mix and match ideas and build your own system. Most important of all, keep it simple. Don’t overcomplicate. Interconnect your notes. It will take time but the results will be great.

I made a promise to myself to write more.. and I kept it, even if I didn’t publish most of what I wrote, I have more than 3000 A4 pages worth of notes and writing. https://andreiclinciu.net/article/a-new-kind-of-promise/

There is no perfect note taking app, just start taking notes

Start with either SilverBullet OR Zim Desktop Wiki, it has everything you need. Yes, you can export to markdown,html, pdf. And you can collaborate with other technical people through git or fossil scm.

One pitfall is to try to search for the perfect note taking app. Please don’t start migrating your notes and going from one app to another. Don’t get caught up in the zettlekasten knowledge management trap.

I’ve been there and you will spend more time fiddling around making a system work for you instead of taking notes. This is not healthy nor sustainable I’ve actually built my own notes sytem twice and used things like vim and tens of different software. https://andreiclinciu.net/article/note-taking-simplicity-fossil-markdown/ You can use hugo static site generator for pdocumentation and even notes (https://andreiclinciu.net/article/tech/hugo-golang-simplicity/)

If you plan to collaborate with other non technical people then you might want to take a look into Wiki Go or usememos .

But I strongly recommend SilverBullet which we will explore in another day as it’s programable. (Theoretically they all are since they’re open source, but silverbullet is more special in this aspect;)

Plaintext is the best format to use for documentation and notes

The best file format to use when writing ideas is not html, not some private binary format, nor word docx/odt. Keep it in plaintext.

There are quite some plaintext options including markdown, asciidoctor, etc.

Asciidoctor provides many extensions which are lacking in markdown.
It’s supported by github by default, it’s used to build books PDF’s and epub’s, you can template and design it. There’s even a presentation module with revealjs for asciidoctor. Even if you don’t use asciidoctor, keep your notes in markdown or a variant which will work on any device while used in any source control management system like Git or Fossil SCM.

Start Writing NOW

Download ZIM Wiki (or open a .md file) and Start writing NOW.