Day 2: The Art of Writing - DevOps FullStack Secrets

Writing is an integral important part of what we do in the modern 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. You’re writing. All the time. Writing is a form of communication we need and do on a daily basis; SMS, 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. Take the 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 - Externalize information through writing - Building a Second Brain

We can’t store everything in our brain. This is why it’s much more important to be able to know and be able to solve a problem 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. Let it incubate, and come back later. 1 day later is perfect.
2. Read it, edit it and iterate as many times a you want. THe more you EDIT the better it becomes. The more you will train yourself to remove excess the more succint you can become. At the beginning you will probably write 3 A4 pages for an idea and then summarize it down to 1 A4 page.
3. AI atrophies your brain- You loose valuable creativity, thinking, memory and communication skills.. Don’t use AI unless you want to brainstorm or want to gather intel on how to present an idea to stakeholders but already provided it with a lot of ideas. Always use your OWN brain and thoughts. Instead of externalizing your thinking, you build valuable skills. Becoming irreplaceable. Your brain is accumulating cognitive debd when using AI assistants which impact creativity, critical thinking, memory and communication skills². All essential to succeed in life.

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.

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

Start with 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.

You can experiment with SilverBullet, VSCode + Foam(keeping this locally), or Vim/Neovim.

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 either. All apps have pro’s and con’s.

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.

You can use [hugo static site generator for documentation]((https://andreiclinciu.net/article/tech/hugo-golang-simplicity/), we talked about Hugo yesteday and even notes or something as simple as Fossil SCM + wiki

If you plan to collaborate with other non technical people then you might want to take a look into Wiki Go or usememos (not the react hook, the golang notes app)

I strongly recommend Zim Wiki or SilverBullet (which is programable)

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.

Plaintext will be readable in 100 years, while we don’t know if binary formats will still work then.

There are quite some plaintext options including markdown, asciidoctor, html, 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 any editor and start writing in asciidoctor or markdown NOW.

Tomorrow you’ll get started with Virtualbox Virtualizing Linux