article

· · to read

In my recent talk yesterday, Documentation for AI and Humans, I discussed how the role of the technical writer is evolving to meet the demands of a dual audience: humans and AI systems. This isn't a minor change; it's a fundamental shift in how we approach documentation.  

We explored several key aspects of this transformation:

  • The Rise of AI Agents: AI agents are now active consumers of documentation, using it to perform tasks and automate processes.  
  • AI Processing vs. Human Reading: AI and humans consume documentation in very different ways, requiring us to adapt our writing style and structure.  
  • Layered Documentation: Creating different layers of information (strategic, tactical, operational) to cater to different needs.  
  • Structured Task Flows: Documenting procedures with explicit steps, expected outcomes, and troubleshooting decision trees.  
  • Machine-Readable Metadata: Embedding metadata within documentation to aid AI interpretation without disrupting human readability
  • Documentation as Code: For AI, documentation is increasingly becoming executable, blurring the line between traditional documentation and software.  

The future of documentation demands a dual-audience approach. By embracing structured content, machine-readable metadata, and a focus on clarity, we can create documentation that serves both human needs and AI capabilities.  

article

· · to read

Last night, after we had finished our nightly routine of a Wordle game (the word was ‘spear’ in five tries), I asked Max what he had learnt in school that day. He said he had read The Open Window by Saki (H.H. Munro) in his English class.

‘Appa, I’ll tell you the story,’ he declared, grinning at the unexpected role reversal. Usually, it was the other way around.

‘Do you know the story, Appa?’ he asked. I admitted that I might have read it but couldn’t recall the details.

As he began narrating, fragments of the story resurfaced in my mind. I had read this story. I must have been his age—maybe a little older. But there it was, coming back in fragments.

When he finished, he remarked that he liked the last sentence: Romance was her speciality. Then he added, ‘Appa, did you know “romance” can also mean a fantasy story?’

With my memory fully refreshed, I gently corrected him: ‘Actually, the last line is Romance at short notice was her speciality.’

Max blinked, then nodded. ‘Oh! Now I remember’.

And just like that, he was done, stretching out under the covers, already halfway to sleep. But I wasn’t.

Memory is strange. I can forget what I did five minutes ago, but a story I read decades back? That lingers. Maybe if I wrote my to-do lists as stories, I’d actually remember them.

After he had gone to sleep, I lay there, thinking about that last line. What could I do with it?

And then it struck me—perhaps I, too, could practise romance at short notice.

I could write vignettes. Short, sharp stories, woven from fleeting moments, laced with memory and meaning.

And so I did.

article

· · to read
The Sirens imploring Ulysses to stay

So I turned 45. What does this mean? Am I considered middle-aged?

The advantage of owning your domain is that it is an eternal sandbox that you can always play with. You can build it up or raze it down to rebuild again (and again).

As I start off my 45th year, I am looking at this refresh as a new chapter still trying to make sense of blogging again.

I've stopped posting on social media for a few years now. Most of my accounts are gathering dust and a shadow of what it was in their heydays. Social media was interesting when it was still in its nascent stage. My dissatisfaction with what social media promised at the start and what it has become now is another reason why I'm trying to start writing again on my own site.

But then again, I'm considering it a new start for the my #year45.

Let's see where this odyssey leads. And I hope I can resist the siren call of social media and use this more.