Hey there! This is Platform Weekly, the newsletter that makes catching up on cloud-native like the first few days of spring: unexpectedly hot. 😉 Let’s get bakin’

5 tips to make your docs more successful

Olga Merkulova, Product Manager and Solutions Analyst

Breaking news, Instagram Reels, TikTok, and YouTube Shorts, oh my!

Living in the era of information intoxication means the average person’s attention span in 2022 is ~8 seconds. No wonder it’s hard conquering readers’ attention with your documentation. That’s why it’s important to make your docs exciting and interesting to read, here’s how 👇

1. WHO → WHEN → WHY

Find out who your reader is, when they will read your docs, and why. Keep in mind how they will find your documentation and under which circumstances.

2. Don’t start right away!

First, think about the structure of your whole documentation and determine your:

- Audience (e.g. end users, software developers, executives, sales, etc)

- Audience level of expertise

- Level of detail you need to put in

- Entry points like “How to” or “What if”.

There are a lot of free templates on the internet to help you with this process. Get inspiration from them.

‍

3. Think about readability

This isn’t just about using bullet points. Below are several techniques of what can be used to architect information:

→ Graphs

→ Concept maps

→ Infographics

→ Short videos or screen cast

→ Mind maps

4. Get creative

If it’s possible to use images to explain, do so. We live in a global world and the less language-specific you can be, the better.

‍

5. The rule of 10-5

This means 10 seconds of reading and 5 seconds of examining one of the readability tricks from point 3. Take into account that the average attention span is around 10 seconds, so consider switching to another way of presenting information after this period of time.

Whenever you think about documentation, think about it in terms of a software development process:

Analysis → Requirements capture → Design → Implementation → Maintenance + Version control.

This approach will help you see the big picture and make it easier to write and maintain documentation.

Short on time? ⏳ We got you 🥐😋

🥐 The folks at Robusta benchmarked Kubernetes providers and node efficiency.

“TLDR; with default GKE nodes, you get half the CPU you pay for. Overhead is better but still noticeable on other Kubernetes providers. GKE autopilot is unaffected.”

🥐 Want to create an Internal Developer Platform your developers actually want to use? Here’s where you (might be) getting it wrong. 🤐

🥐 According to this article, platform engineering makes healthcare developers more agile and boosts compliance. Pretty neat, right?

🥐 Why is TikTok’s recommendation system so damn good? I appreciated this take Damien Benveniste shared to LinkedIn 👇

🥐 Here’s how ChatGPT is changing your job. 👀

Last but not least, have you joined the Platform Engineering Slack channel? If not, you're missing out. Here are some updates:

• What are the next steps for learning about platform engineering?
• You can take this network engineer’s approach and dive into Git.
• Or you can pick up Go or Python like this Terraform user.
• Connect with your local platform engineering group for fun, IRL meetups.

• Don’t know how to drive adoption of your platform? I really enjoyed this discussion on the topic.

And that’s a wrap on this week! As always, this newsletter is a community project. So if you have anything awesome to share from the cloud-native world, send it our way.

Stay crunchy 🥐

Luca

‍