Tuesday Morning Keynotes

 Truth Collapse: The AI Meta-Crisis

 Noz Urbina, Principal at Urbina Consulting, started Tuesday by asking what's going on? He answered that we're not OK. All of us everywhere are being affected by artificial intelligence. 

In the content community, when it comes to AI, I'm getting a lot of harrumph harrumph harrumph. Al lacks empathy and can never reason.

 Who among us writes perfect the first time? who among us doesn't need practice and training?

Literacy reshapes how we think. Logic arrived in the world after writing. 

We live in pre-AI literate societies. 

An AI is a technology can learn. Google's search engine is driven by algorithms, but engineers could always change the algorithm.

AI isn't programmed. It is grown. Like other organisms, we don't fully understand it.

Shining a Light on Internal Documentation’s Extensive Impact

Michelle Irvine, Technical Writer at Google started her talk telling us about research that had been going on for 10 years. The research is on not only documentation, but part of it focused specifically on internal documentation. 

In open source documentation we can pull back the curtain and see a lot of it for ourselves. 

How does it behave in a larger system? We found that documentation quality underpins quality of everything we looked at.Quality documentation affects the quality of everything. It is a pattern that is persistent and consistent. 

Teams with quality documentation are 3.8x more likely to implement security practices, 3.5x more likely to implement site reliability practices, 2.5x more likely to leverage the cloud. 

Teams with quality documentation see increase in productivity and job satisfaction and decrease in burnout. 

Documentation is like sunshine. 

It's not just about more and more docs. It has to be relevant. 

Writers who have taken training create higher quality documentation. Teams need guidelines and style guides for higher documentation quality. 

Documentation is work and is expensive. Figure out what is critical and focus energy in maintaining that. Delete redundant content. Curate to stay fresh and relevant. Value doc work. Where this was happening, we saw an increase in quality. 

The Unseen Challenges and Hidden Costs of Adopting Markdown for Technical Documentation

Scott Abel, Content Strategy Evangelist at Heretto, spoke with about 2 dozen tech writers, managers, and consultants who use Markdown every day, as well as people who use other technologies as well. I held some panels about the pros and cons of Markdown.

Most are using Markdown in a startup environment. The challenges and costs were not the cost of Markdown as much as docs-as-code. So now, Docs-as-code or not?

A fit for purpose publishing pipeline meets a team's requirements for managing, storing, and retrieving information effectively, even if it lacks advanced features. 

Docs-as-code helpful on small team with small, simple, static doc needs. Not better option if you need dynamic, personalized, scalable content. Lot of writers work to maintain publishing pipeline--instead of writing.

First hidden challenge is scalability. Trying to scale docs-as-code is like trying to patch a small leak in your time with duct tape. 

Second hidden challenge is personalization. Docs-as-code has no metadata, so there's no opportunity for personalized content. Nothing is semantic. 

Third hidden challenge is multi-channel publishing. If you can accomplish at all, you have to add additional modules.

Fourth hidden challenge is formatting and design constraints. Particularly difficult in docs-as-code because you don't have as much control over the content. 

Fifth hidden challenge is maintaining a fragmented toolchain. Spending significant amount of time when not done right. 

Sixth hidden challenge are build and deployment issues. As a tech writer, don't want to hear about "build and deploy" unless I'm documenting it. If you buy a software product, it's their job to make sure it works right instead of yours. 

Seventh hidden challenge is accessibility limitations. 

Eighth hidden challenge is SEO obstacles. 

Ninth hidden challenge is cybersecurity. When devs can't find the information they. need, they search elsewhere. Criminals put malicious code there for devs to copy and use. 

Tenth hidden challenge is change resistance. People who have only worked in docs-as-code environment see it as an easy way to get stuff done. They have no incentive to change. And they have never worked in other environments, systems with management and governance. 

No semantic metadata means Markdown is nothing more than a new version of WordStar. 

Why, then?

The developers like it, it's perceived as easy, and it's perceived as free.