I'd Rather Be Writing Podcast: Presentation recording: Specialization myopia syndrome and the content journey

Thanks for the introduction and thanks for having me give this presentation to to your group

Thank you for bringing me back after a number of years

The topic here that I'm going to talk about is called specialization

myopia syndrome and the content journey and

This is really a topic. I've been exploring on my blog for the past year off and on

I want to just introduce a little bit about why I got interested in this topic in the first place

Some months ago

somebody asked me to present on trends and

You know

I've already I'd given so many presentations on trends that I was feeling a bit contrary

And I didn't want to give yet another presentation on trends

so I decided to to

Explore non-trends things that that were once trends, but then fizzled and we're just like no longer a thing people do

so I created a a survey on my blog listing about

15 to 20 different things that I thought people were I don't know that might be fizzled trends things like

Wikis or

help authoring tools or

certain practices around

information disclosure progressive information disclosure and so on and

time and again

everybody sort of

Checked the mark saying that yes, I'm still doing this. This is still going strong

this is this isn't a trend that has fizzled and

It got to be ridiculous to the point that I would I would say okay. Let's find at least something

I was like surely nobody is still producing chum files and

Like within five minutes on some interactive chat somebody was like I just produced a chum file for a client this morning

I'm still being asked for them and I was like this is okay

This is ridiculous and kind of mind-blowing and I didn't know what what to make of this like how is it that everything that was ever a trend is

still like a trend is still

available and and

In some capacity still functioning

I'd heard similar things about products like everything that's ever been a product you can still buy in some form or fashion

But this got me thinking like okay, so what does this mean if there are no fizzled trends?

And sure some technology supersedes other technology, but in general

What would what would we conclude if everything that was ever a trend

doesn't really fizzle out, but just sort of gets added to an ever-growing collection of

Practices tools

techniques

increasing the sort of

technical diversity and

options available and

That's that's what got me. Got me started on this and I was like that is a really intriguing topic

and it

sent me about

Exploring non-trends and

The these sort of technology trajectories

That we have so let me

Jump into the agenda outline and my main argument that I'll be talking about today

So the bullets on the right are the main topics. I'm going to talk about

Technologies trajectories the impact of specialization on docs

Opportunities opening up as a result five ways to focus on big-picture docs as a tech writer and some

Realizations and takeaways and my main argument is basically this as technology becomes more specialized

Big-picture narratives are becoming lost and this gap opens up opportunities for tech writers

So this is actually

kind of a really interesting

argument and topic and and one that

You know is not without many many challenges and nuances here

but since I have ample time to kind of get into and and

Describe the context of this art of this whole argument and and the topic

We're gonna go through and build this up

Also, because I know that it's very difficult to sit and watch a presentation for so long

I've included a lot of kind of questions that are hopefully

We'll bring out more interaction into this presentation

Well, let's start with technologies trajectories

There's this quote that I was I was reading in various books or I kept seeing in various books

by Karl Marx the famous

philosopher economist and

He the quote is the windmill gives you society with the feudal Lord the steam mill

Society with the industrial capitalists and the idea is that certain

Structures give rise to certain outcomes like if you if you have a windmill

Then it naturally follows that society is going to develop around these feudal Lord systems

Or if you have steam mills, you're gonna end up with industrial capitalists and so on

Now I'm no expert in that that area

But it was an intriguing thought that like maybe you can sort of see the future based on your current conditions

the patterns that that are in place now give rise to what will

Eventually be the outcome and I as I was reading this I was going through that through this techno skeptic phase

Where I was like renouncing my smartphone and trying to like go off offline more

And I was I was convinced that like okay because so much information on the web is free

That means the inevitable way that people monetize is through ads and what happens when people monetize through ads

Well, then you have this whole attention economy

Develop where people are constantly trying to hijack your attention and what happens when you have that that attention economy

People's attention spans get fragmented and so on. I was like is it really possible to sort of trace out the

The outcomes based on your current conditions. It's a really intriguing thought and then so

There's another book that I had been hearing about for a while this book called

What technology wants by Kevin Kelly and

Kevin Kelly is he he's really really interesting figure. He's like one of the one of the early internet leaders

He was he's co-founder of wire, but even before that he was involved in an effort called the

whole earth catalog which is some kind of

Catalog of tools to empower people against

Other other, I don't know. I don't know how to best describe it. Anyway, it was kind of like a techie hippie thing

But anyway, so in this book Kevin Kelly

He outlines it's a fascinating read. He's talking about

Technology and he describes it as as almost like a growing biological

Organism that that was first observed maybe a couple hundred years ago in different places

He says, you know people didn't always just have the word technology and and think of this as a concept

It was like sure people have had little devices, you know little inventions here and there, but

Technology is something that started to grow

Especially once the industrial revolution hit and become more more visible in places and people started to talk about it more

and more just

Recently in the last century and so on

and

And hey the ultimate question. He's trying to decide in this book as well. What's what is the ultimate aim and trajectory of technology?

What does it want? What is its predicted outcome and he concludes that?

Well technology is it kind of wants the same thing that that most life wants it wants to expand and proliferate and

sort of consume the earth

He describes around

Eight eight or nine different clear trajectories that he sees in technology

complexity diversity

specialization

Ubiquity freedom

Mutualism beauty sentience structure and evolvability and he talks about each of these in really compelling ways

Though the three that jumped most out at me jumped out at me most

Were complexity diversity and specialization

the the

The whole like diversity thing and when he's talking about diversity, he's talking about like technical diversity like the number of options available

That's a really fascinating one. He talks about like for example

If you think of a shoemaker

Initially, if you had just one shoemaker who who was an artisan who could make the shoes from start to end

it would take that shoemaker like a

Long time to make a pair of shoes

But as people sort of got smarter about production

They they had a crew and each person would specialize in different areas of making the shoe

Some people would build the heel and others would do the stitching and others would would do the sole and so on and

When you started to specialize the roles the number of shoes that that people can make

Increased and then as people built factories where you didn't even have humans that needed to get involved

You could produce even more shoes right so as as specialization of roles has has become a

Best practice so has the number of shoes

That could be produced and now

If you go to Zappos, he said and this is this book is like 13 years old

He says that you have like 90 different thousand options for shoes or something whereas, you know many many hundreds of years ago

You had just a few different shoe options

This this specialization is giving rise to abundance

There's a lot of there's references to the wealth of nations and how the specialization is what gives us

It sort of unlocks this this wealth

But if you think about it like today

He says like even in our house if you were to count the different types of things in your house

Compared to what was in a house?

Thousand years ago

It would be mind-blowing. He started counting all the items in his house and there were like 30,000 different types of things in his house

I mean, he's not just counting every fork

but like fork and a spoon and a knife and and different kinds of utensils and plates and everything

in your garage and so on it it's sort of

Like kind of crazy to think how many different types of things we have

That that just wasn't part of life

Hundreds of years ago and why is it well in part because of this

Function of specialization that allows so many different

groups to produce more

more things more types of things more varieties of things and

It's giving rise to this this diversity think also about like mobility

Used to be that you you had a car and maybe a bus and a train and now you you have so many different options

You've got like five scooter options e scooter options in a city and in e-bike options and car sharing options

different companies and so on

for each of them and as well as

Your own plethora of vehicles that you can choose from and and so on and different routes and different ways of getting from point

Eight a point B

So a question as I was going through this complexity diversity specialization

I started to wonder well

What is the inevitable conclusion as a result of these characteristics?

As far as complexity that one's a little more straightforward, but he talks about how

You know scientifically the world started as a like a quark

and then you get a subatomic particle and then it grows into an atom and then you sell and

A little organism and it gets more and more complex until you have

conscious humans and so on

This complexity is apparent in every aspect of the world

Complexity

around

Not just you know physics, but around

Ideas he includes ideas in this in this group of growing. He calls it the technium. It's growing technology

The ability to manipulate thought through language and expand our ideas through through printed books and so on master

Distributed and and the growing

Collaboration of ideas is also something that's increasing in complexity

so the question is

What outcomes will naturally follow as

Technology gets more complex more specialized and more diverse

So this is a part where I'm trying to I would love to

Sort of get your thinking wheels turning

So so

You can you can use the meeting chat or you can use you can even unmute if you want it

but use a meeting chat maybe mostly and

Just I don't know throw up an idea. What's the natural outcome of increasing specialization?

Especially as it relates to maybe tech calm. I'll give you a minute to think about this

Okay, and I want to kind of focus more on like the impact of specialization on docs

There's an article. I was reading by by an economics professor John Davis called specialization

fragmentation and pluralism in economics and

Just one little quote. He says researchers have a decreased

understanding of research

Programs outside their own operate in relatively isolated research niches and it is less and less clear

What unites research programs and makes economics a single discipline?

So he's focusing on economics, but it applies obviously to other disciplines too and this this person is kind of saying hey

How is specialization changing the field of economics?

What's happening is that all these little sub-disciplines are starting to crop up

They're breaking apart into a little tiny little from one big planet to lots of little planets

And they're sort of operating in their own world

Asking their own questions and it's less and less clear like they don't all they're not all trying to answer the big questions

That used to unite economics as a discipline

And as a part or as a result they're sort of breaking apart and creating just these separate separate sub-disciplines

We see this happening in tech calm

Used to be I don't know 20 years ago

That you were essentially a tech writer or and that was that was what you did

Now there's lots of different flavors of tech writers. You've got you've got the whole UX writer

Sub-discipline, which you know, it's like their own there. They're a different group. They've got different concerns and

different

Topics you've got the content strategists. There's they're sort of broken off into their own group. They've got their own conferences and everything

You've got the tools people who are

You know have separate concerns as well. They're mired in in complex tool chains and

Transformation technologies and even among the tools people. There's huge differences. You've got docsis code people. You've got XML people

You've got content management system people. I

Guess the XML and the content management are more closely combined, but

You definitely have different different groups

What else among the tech calm people you've got a group of editors, you know, you've got

People who are are focused on

maybe life sciences

more than like high-tech and

The people focused on on different things and and all these little subgroups, right?

We still put them under the larger umbrella of tech calm, but in a lot of ways

So much of the content becomes less and less relevant to the larger group. I remember going to STC conferences years ago and

Kind of being blown away by the fact that there were 10 concurrent tracks going on at the same time

I was like, wow, you know, surely this is gonna be fascinating and then and then being sort of perplexed that that not a single

sort of

Representation or session was really appealing to me in that session of 10 concurrent tracks. I'm like, how can this be?

You know, one was focused on translation and another was focused on like video production and something else

I'm like, wait a minute. I'm not doing either of these, you know, and and it was another maybe was an academic topic

You know academic methodologies or research or something who knows

But it just goes to to show that we've got all these separate niches that are starting to operate

independently as a result of this specialization

another

Outcome of the the impact of specialization is increasing comprehensibility. This is a quote that I pulled out of a book

on

Systems systems thinking the quote is by John Raston Saul political scientist. He says

Rational elites know everything there is to know about their self-contained technical or scientific worlds

But lack a broader perspective. They have a common underlying concern

How to get their particular system to function

Meanwhile civilization becomes increasingly directionless and incomprehensible

And this this quote

When I read it in the book, it didn't have any context

I'm like, wow, this is kind of really interesting and it comes from this book by this guy

Saul who was writing

against this rising trend of

Rationalism and he's pushing back against the idea that rational

Logical thought is the only way that we can know things and he he's kind of like trying to raise

Awareness of different ways to know

And he's saying look these people who are so steeped in in in their own little

Scientific or technical worlds. They've developed their own jargon and they're no longer like interoperable. You have one person

who

Like they can't even really talk to each other anymore because their jargon is so specific and and this is definitely an

outcome of

Increasing specialization is that you've got increasingly specialized terms and those terms sort of lock people out of your discourse

And if people can't speak your discourse, they can't really interact with you

And it reinforces this sort of siloed isolation of the different people

You know if I were to go speak at even a UX writers conference, I don't even know the right terms

That would make me sound

Would that would allow me to plug into their their topics

Probably the same with many others content strategy localization even within the same

Discipline there's just this increasing incomprehensibility

And even if I were to try to write an academic article

there's an example where there are really highly defined

structures formats

conventions expectations discourse and

and

Anyway, this is all an outcome of this increasing specialization of these different roles

This this book. Oh this quote by the way comes from this book called Voltaire's bastards. I believe which is apparently a really long

Diatribe against this. I haven't read the whole book, but at one point I will get into it

Okay, so

Now what about the impact of specialization on a developer portal or a dock portal

what I see are

Building blocks, but no picture of what you're building you get the how but never the why you there's no larger story no

Customer journey no enterprise context, you know, how does this product differ from others within your same company?

Or how does this product differ from others within the larger domain outside the company?

You know, there's no context. It's just like hey, here's this product. Here's this API. This is what it does

There's a site fragmentation

You've got one dock portal for this group and another dock portal for another group and many times you're just shipping the org chart meaning

One org likes to have their own dock portal a different org has a different dock portal because the the same

Organization lines are manifest in the way the products are differentiated and they're all sort of siloed from each other

It's like one group works on their their dock portal or their their little kingdom

Another group works on theirs and they don't really interact because they don't have a need to

It can be even as embarrassing as as realizing at some point that the two groups have named

An API the same or they've got a similar similarly named product and it's unclear even to the people within the company

What the why the company has two duplicate products or why there's redundancies how they differ and the

Documentation clearly doesn't like elaborate either

I

Don't know if this you know

It rings a bell or or hits any points of relevance. It's more true in some companies than others

But this is something I've noticed in in different companies

I've worked for where the developer portals just sort of take on this this increasing

incomprehensibility

you know making sense only to the specific partner that maybe they were designed for and

Know like awareness and integration into the rest of the information into any kind of coherent story and journey across it

Now documentation also begins to

Start to become specialized as well and in part this is because docs just mirror the same perspective that engineers have

You know engineers, they're often too specialized to communicate a larger picture to tech writers

They they're fixing a bug about a certain data point or something

You know and they understand a very small sliver like we need this documented

So they reach out to the tech writer who documents, you know the same

understanding as the engineer and

so then the documentation begins to reflect the same engineering specialized perspective and

You never sort of break out of this tunnel vision syndrome of just looking at oh

This is what this data is not like well. How is a how is a partner using this data?

Or what's this larger API for how does this fit into a developer journey? Like what what's this larger story?

It just sort of gets lost and there's not a lot that

Tech writers can do because if our main source of information is the engineers

Then we're basically just sort of regurgitating and and and putting

Into articulate language their understanding of things

Another challenge is that this larger story starts to become missing

Based on the whole

Development process of Agile itself, you know Agile's this response to the complexity of developing a product that meets a user's need

In the waterfall approach people spent like two years just working heads down on a very defined set of requirements that were upfront

defined with

The customer and so on and people realized oh by the time the two years is up

We're straight way off course

So let's just develop in two two week increments and check in regularly to see if we're on track

So you end up with sort of an external partner or external customer being a co-developer in this process. Well

If that's how you develop your products

They'll probably be more aligned with the customer

But that customer that it's developed with no longer needs this larger story because they're like heavily contributing into the co-development and

Once the product is done there doesn't seem to be a need for an overview the the

Partner just needs like the tech notes on how to use it

Because they they understand the purpose for which they they defined it

But then as you try to to break out of that one-to-one development path and do a one-to-many

Application of the product all these other partners that weren't co-developers are suddenly lost. They're like wait a minute

What's the largest story here? Like why?

Why does it work like this? They don't have that whole context and

by by the time the products launched the tech writers probably

moved on to other

projects

There's also an impact on engineers I find that engineers they seem

More more and more quick to just draw boundaries around what they know and need to know

if I'm asking them

information about a project and I try to you know poke their brain for some larger information they

They're often, you know point me to somebody else or they'll be like, you know, I just want to know exactly

Or I just want to

Discuss exactly this component or widget that that I made

not

Elaborate on how it fits into things

This syndrome of working on a widget rather than a larger product is a key theme and in systems view thinking

And and as people sort of become alienated alienated from their product outcomes, you know, they're just working on a widget

I'm just working on this data attribute. I'm just working on this one tab

The work sorts so sort of loses meaning

I think that's a a Marxian concept about the alienation of labor and so on but

Definitely if you're if you're writing docs and you're no longer

Focused on a larger outcome and you're just like hey

I'm updating this paragraph about this piece of data

Then work becomes a lot less meaningful and as everybody starts to have the same perspective of focusing on just their little part

Their own little widget and and they lose track of this whole

There's an absence of responsibility of something fails of the product flops, they're like why did my part, you know

I my widget worked or this service was functioning and

You know, there's less of a sense of responsibility

And purpose about the whole thing you've seen. I don't know if it's correlated, but

Tech worker burnout is is not a theme that hasn't been pretty constant

The impact of tech writers is also prevalent roles are

shifting away from

authoring due to how complex a lot of the content is

there have been many times in the past where

Developers have an update

It's really complicated and we'll just say can you take a stab at it? Like can you just write the

Write the update and we'll edit it

You know in these these other roles that that tech writers play editor publisher curator

They're also sort of diminishing in importance, especially with this whole emergence of AI tools

Now if you used to be that like

Our language editing was was

Highly priced and and you can see almost overnight that suddenly AI tools can can replicate articulate language

I was just playing around with something called word tune spicy word tunes and

Others to rewrite paragraphs that are awkward. I'm like, ah dang, you know, so all the

Developers who struggled with English now. They've got a lot more powerful tools and then publishing has also become much more simplified

At least in a lot of big tech companies. They follow dox's code. It's highly

highly similar to

The same workflows that the software developers use they're writing in there in in text in their IDEs their

Developer environments and they're they're submitting

through

Processes like git to do version control, you know, and the whole thing is very similar to them

There's no longer this need for an expert in a certain publishing tool that that only the tech comm group knows

And then curation, you know, our ability to organize topics in a sidebar and to group things logically

Sort of becomes less and less important as we drown the document portal with so many articles that

There really is no organization other than search and this search gets better and better

You don't need as much curation. So

this has kind of a

depressing impact on on the tech writing role as well

This leads me to my next interactive question here

How has

increasing specialization complexity technical diversity

How has it changed your role as a technical writer?

So let's take a minute here reflect on this and I'm gonna I'm gonna glance at the chat and see what I can read here

All right, um

The the larger direction here

I've been going is to make this argument that the big picture narratives are becoming rare

And here are a few more specific ways that that we're not seeing these larger store anymore

Detailed product overviews are becoming less common. It's like a two two paragraph

Overview now and many products and that's barely get a sense of what it's about before it jumps into the how-to

The architectural overview that would kind of have a diagram of how things function and interact is often missing

The system overview like how a product fits into a larger system is often not there

The developer journey, you know, how what's the the developers path through a product suite to implementing something is often missing?

End-to-end workflows from one product to another

Especially if those products cut across different parts of the organization is often missing any kind of context within the larger domain

especially

Even just like within the enterprise. How does this product compare with other products?

Within the same company or if you're able to compare it with products outside the company, that's often gone

A life of a something narrative is rarely present. This is a

Document type that sort of traces a path through various workflows and services

And so on so all these product stories comparative analysis is becoming lost as people become more granular

And specialized and focused on very specific things

I had an example the other day that I that I really liked him my daughter came home

She's a senior in high school. She came home

She was supposed to be reading Macbeth and she was like really frustrated because this is the text that they had

Was very unhelpful that this is the text on the left are footnotes that explain language points and on the right is

The original text and the idea is they're supposed to read and they hit a passage that or language

It's unfamiliar and then they they go and

Read the explanation in the footnotes. Well

She was in tears because this is not working. I had no idea what the plot was or how it was

how it how it

Had no idea what the plot was or how it was like

How she was supposed to

Answer this long reading log of all these questions about the characters and the themes and their motives and so on so my wife said

Callie you're approaching this totally wrong. You don't just start reading Shakespeare like this

You need to start at the high level. So we watched a YouTube video called Macbeth in seven minutes

Which then gave her a very clear sense of like what the plot was even about and then we dove into a little more detail

With act by act summaries by something called English Psycho English Psycho teacher interestingly enough

this person has an amazing penchant for clarity and

She would pull out key quotes and kind of get more into detail each of those acts was like five to eight minute summaries

of what's going on and then there's also cliff's notes that that I guess most

Students these days have never even heard of but it's another way of getting into more detail

And only after you kind of go through this high level

Does the actual text make sense?

Now that's with Shakespeare, but it's very similar to a technical topic. You don't just dive into

You know the the nuts and bolts of some incredibly complex thing like let's say you're

Describing the open api, you know, you need to start at the high level and then kind of get more and more detailed

But without that big picture like the experience is terrible for for users. We need that big picture

Another example, I noticed

From going into Ikea

If you have ever gone into Ikea the most

The funnest part of the whole store are these showrooms that show how all the products might go together

and compliments and fit each other

in a room, you know, you get a complete living room for under

1670

I don't know however much the all the items would cost and and of course

I don't think anybody actually buys all the items in in a living room, but it's fun to see how the products fit together

And and imagine like Ikea without the showrooms it would just be

Isle upon isle of products that that would

Be very boring

And documentation is the same way if you have kind of a showroom of hey, here's how this all fits together

Here's here's like the bigger picture of how this works

It's way more interesting than just like here's what this data attribute means and here's this api and that api

All right, so I I believe there are definitely

opportunities opening up as a result of this specialization

And what if tech writers were to exploit this gap? What if we were to

Say look if I zoom out and look at this big picture

there's a lot of opportunities for

Contributing unique content that nobody else is doing that nobody else can do anymore

This sort of contribution

To write the larger story

Um

Might be compared to building a skyscraper versus a dog house

when I was back in in

creative writing school

Long time ago somebody once asked one of the professors

What's the difference between writing an essay and writing a book and she said writing an essay is like

It's like building a dog house versus building a skyscraper. That's what it's really like

You you might have to interface with a lot of unfamiliar teams

You might have to chase down a lot of different reviewers

Or read much more content right at length. Maybe this is

6 000 plus words and stay focused on a project for

months um that kind of work is is harder because

like there's a certain high that comes from

Pushing out a doc change and and publishing it every few days, you know, we want to see progress and feel like we're doing something

Um, it can really be hard to to get bogged down in this larger story

And the audience also changes anytime you're writing this larger story

Who then is the audience? Well, you have people who are maybe doing internal onboarding

They want to see how this new product fits into the larger scope of things or you have

prospective partners trying to understand

the product scope

Cross-functional roles are kind of rare, but um, you know business development product management people

Definitely need to have this view

In other generalists and then senior managers are trying to execute strategies that kind of go across across different groups, but

But the the run-in-the-mill worker who's just trying to fix a bug

might not find this content relevant at all which

creates other challenges because

um

You know, if nobody's nobody's asking for it, it's really hard to find the bandwidth to write it

Now I want to get more concrete here and provide five

Ways that you can kind of use big picture thinking in tech comm

Five very concrete things you can do and and i've done all of these different things

I didn't want to just make stuff, uh, or theorize about about ways in my head

And there's probably a lot more you mentioned the terminology thing, which is something I've completely missed here

but that's would be a very valid one to add

and uh

Let's say I think I'm supposed to go to around 815 or so uh with some time for q&a

but

Definitely could spend like entire presentations on each of these and I won't

The detailed product overview is where I'll start

I think these are becoming

More and more anemic product overviews. Um

I think a detailed product overview is one that's not just a couple of paragraphs

But one that includes like the use cases for the product a high level architecture and in-depth kind of overview of what the api

Is for how it works as well as like context that distinguishes the api

I'm using api

But whatever the product within the enterprise like how does it different from other products and

How does it like solve pain points in the industry?

Now the product overview kind of overlaps with with marketing overviews

So if you have those, you know, there's certainly uh more it's a lot trickier to figure out which gaps to fill

But if you don't um, it's definitely a lot of opportunity here to

To do product overviews in more detailed ways. Um

Gosh looking at this slide. I'm like man, why did I put so much text on here?

Let me just pull out a couple of salient points

product overview is

Something you don't write until you've basically written the rest of the documentation for a product because it requires you to understand the whole product

And and that sort of high level view is something you don't get when you're just jumping into it

um

I've got a whole section in my api.course on product overviews if you want to dive into that

Definitely check out this this link or just go to my api.course

I've got like a sample list of what I think should be covered in a product overview

And uh, the product overview is the most relevant and kind of easy place to start in terms of like digging into more detail

Um, let's look at a few less less immediately apparent applications of the big picture

developer journeys

this is um

Kind of like the path this is probably more developer centric

But like the path somebody takes in implementing a product

And all the different like parts of that journey

uh, I I remember

working on um

Something like this when I was at amazon

Uh, I would I wrote a a journey for developing fire tv apps versus roku apps

And I and I pulled out like eight different steps along the way

And it was like, okay. Well first they're gonna, you know, they're gonna sign up and then they're gonna

They're gonna build the app and they're gonna do that

Then they're gonna be publishing the app and so on I compared it each way between fire tv and roku and it was actually really fascinating

I was like, why didn't we have this before?

It gives you a lot of uh, it gives you a path that you can kind of hang content around in in the structure and shape of your developer portal

As you as you tell this larger story

um

Some general notes

I noticed language totally differs when you dig into a competitor's

Docs, it's like, oh, they use channel in a way that we're not and you know, that's totally confusing

But once you once you define this developer journey, it really makes it

Uh, it makes it seem like when you didn't have it. How did you even function? Um, because it really structures and grounds so many different things

Right another

Another implementation is a cross system workflow

By this I mean some kind of workflow that traces

traces, uh

Some path of information through different

services, um

I said about doing something like this recently that I titled life of a commute

It describes sort of everything that happens on the back end when you route to a place on google maps on your phone

All the different services that come into play and there were like 20 different services

It was actually quite fascinating how it all worked. Um

But uh in writing this I realized like

Whenever you have a workflow that cuts across different parts of the organization

There's often there often aren't docs for this like most people

draw the boundaries of their documentation with the boundaries of their team

And and their stewardship, but but often products that are massive in scope

Have multiple teams and multiple parts of the org and they're not just

Limited to to one little group. So I stitched together

This workflow across many different teams and groups and and it was kind of fascinating

Um

Again this involves working with a lot of unfamiliar teams didn't know me, you know, and then of course now I've got content that

Who knows when I'll need to update it? Uh, because I'm not in close contact with those teams. Um

But then again

sticking at this high level

Uh without getting too granular in details. Wasn't that wasn't that challenging?

All right integrated data for multiple apis. This is another effort that I think is highly worthwhile. Um

Uh, for example, let's say you have four apis and they return like data, right? Well

Maybe some of the data is the same or some of the data is is highly similar

Um, how do you present it all in a way that the user can can browse and navigate without

requiring them to just kind of

Go explore the javadocs for each individual api

that sort of

comprehensive list of data attributes that you get back or data that you get back

can give

Uh, the user a one-stop shop in understanding the data and that

That view is something that uh, no matter what kind of reference docs you have can be highly highly valuable

So many different teams have their own little

slice of the data pie

And you can bring it all together

Um

In working on a project like this, I realized that I didn't really need writing skills. I needed document engineering skills

Ended up creating templates and working with

ginger syntax and so on

And then trying to figure out how I was going to keep all this stuff up to date

All right, the last one is to to develop external domain knowledge

All right now external domain knowledge, this is probably the most controversial of them all but

um

One thing I've experimented with is running a book club

You know a group of people focused on reading a book a month about a topic

That's relevant to whatever industry you're working in

Um, you can get very relevant and thoughtful discussions and more than anything

Yeah, books have

The external perspective how do other people view this product this company this space?

You know, um when we're working inside of a company

Our view tends to be very kind of like narrowly defined within the same company's perspective

and when you read books or

Or magazines or journal articles

outside your company but within the same domain space

It can present you with a lot of like new views and ways of looking at things

In in this book club

activity

I've read many books where i'm like wow, I didn't realize I didn't realize that people, you know had that perspective or

And many times it can be challenging like oh

That's a different way of thinking about things that I hadn't heard inside this company

um

Now the book club is a lot of sort of extracurricular because it it doesn't it doesn't tie directly to a documentation output

But it would make your group become

Or would help you sort of give the impression from your group

That you're a deep thinker a broad reader and more of a knowledge expert in the area and that could be valuable

Um

This is something I mentioned briefly with the the fire tv roku app thing

App example, but when you read from your competitors docs and information

It's kind of a very eye-opening. It's hard to sometimes get into that space, but just the whole language

Uh element becomes

like blown wide open

Okay, so I'm going to end it right here

I do have some more slides, but I wasn't sure how long I would I would need is kind of a long time to

Plan for

But this is my last question. Which of these document types have you written before?

Why or why not and what was the result? These are kind of

Interesting categories of information that aren't often emphasized in the traditional tech comm output that we produce

Let's see if people have um any responses to what kind of

What kind of content like have you have you worked on anything like this? What was the outcome?

Or if you haven't why?

Let me glance through the chat here

um

Let me just uh jump to one more slide here the the challenges that sort of crop up when you zoom out

Um

Ownership of documentation becomes thin, you know readers change

Uh, it's almost like extra credit dock work

Because a lot of people aren't asking for this. So it's there are really some challenges to solve

But I I truly believe that like this is where our value can best be made manifest

Is is when we zoom out when we look at the big picture in some way try to integrate things across different groups

Uh, whether that's terminology

concepts

Uh, what as we we try to understand

The developer's journey or the user's journey and and how our product fits in there. What are their milestones?

These are things that more specialized workers are not focusing on

and uh, and

This value then will sort of validate our role, but also just make, you know, a better user experience. So, um

That's all I I had there is a blog version that you can read on my site

It's this series called trends to follow or forget. It's still kind of rough and

It's actually a whole big section on very specific trends that I was I was exploring

But uh, this is as I said, this is a series

Um that I'm exploring trying to get better at at understanding the larger

Label is like systems view thinking and so on

It's this idea that the sum is greater than the individual parts and the idea that uh an impact in one part

Um can have an outcome in many other parts

But uh, thank you for attending you can read more on my site you can check out these slides if you want

And uh, you can reach out to me through email in other forms. I'm happy to continue the conversation

And I really appreciate your input throughout the this this whole presentation. You've got many

uh

Smart people who seem like they're

Well versed in the value of this big picture and zooming out. So thank you

Machine-generated transcript that may contain inaccuracies.