Hi, I'm Daniel, I'm a technical writer and I've made some mistakes.
Prepare for this talk, I was looking back on the larger open-source documentation project.
I have been a part of, so not one of tasks, but kind of big multi-step projects.
And I really wanted to tell you about a success when this is not that talk.
Instead of coming back to a tiny failure, genuinely tiny failure,
I am kind of haunted by my very first attempt to lead documentation work for open-source software project.
I was a technical writing student at university, and I needed a capstone project with real clients.
And a lot of my classmates were doing unpaid labor for their employers.
And I thought, you know, if I'm going to work for free, I'd like to be for the comments.
And I was a computer science student before getting into tech writing, and so I was like, alright, I've never been here.
Open-source.
And I reached out to the containers of Python library that I used and was fond of.
And to protect the guilty and the innocent, I'm not going to actually read you my print email.
But the conversation with something like this, I am a tech writing student.
I want to work on your documentation.
I could have be ready to use a guide or fill in some undocumented API references, or have a bunch of undirected ideas.
And the sound of the project was actually quite enthusiastic about this.
He said, oh my gosh, a real tech writer to work on a docs.
I've got some ideas too. He's written on my suggestions.
And then he says, what do you think, maintain or be?
Well, the other maintainer for the project says, you know, this really sounds nice.
But as the primary maintainer right now, I, I don't think I have time for this.
I wouldn't be able to mentor you and how to use Git or how to fill the docs or do anything like that.
And it's not worth to change anything about the docs until the big two dot zero rewrite is finished.
This is not how I wanted this conversation to go.
But in this conversation, in retrospect, I did that every single thing wrong.
We're actually, we both did. We had vague outcomes.
We had bad assumptions about what a tech writer could and should do.
We had bad assumptions about what a maintainer could and should do.
We had no explicit connection between contributor skills to the actual needs of the software.
And we even couple docs work unnecessarily to other activity.
This is not a catastrophe.
In some ways, I was very lucky. This could have been an ambitious project that blew up my semester.
Instead, I, like everybody else, I did some pre-work from my employer.
Now, that version two does your rewrite.
Shift used after I graduated.
We just didn't do anything in this respect.
So we had the classic failure mode of software documentation, which is to do nothing.
So in the last few months, I've been thinking a lot about this very early episode of my career.
And I've been asking what it would look like if writers and developers knew how to work together from some very early conversations.
And the rest of my talk is about three common high consequence problems for open source free software projects.
When it comes to maintainer and tech writer collaboration, some ways to think about those problems.
Some problems with the way of thinking about those problems.
And a preview of a free resource to help you do this work in a very practical actionable kind of way.
The problems that we get into here, they're not actually, they're not almost common problems.
The other ones that I think you're probably already familiar with, like scope creep.
I'm not going to get into, but I think these are most interesting and most damaging because they're widespread.
They're kind of invisible.
They undermine trust between collaborators.
And they have negative consequences for the consumers of your documentation.
So when I talk about maintainers through this, I want you to understand that I'm not throwing stones here.
I also an open source software maintainer.
I have been on both sides of these conversations.
I've made some sticks.
And I'm not cater.
So problem one is inwardly focused.
It's when a maintainer fails to recognize their own capacity.
What time do they have available to do work?
They're skills.
What are they good at?
What are they bad at?
They're assets.
What existing docks and tools are already at hand?
And avenues of support.
Who can they turn to to get advice or additional help and that kind of thing?
This can cut in two directions.
You can have over an underestimating.
So for instance, a very confident thing can experience, you know,
Halifax and can see about their own skills and the superficial similarities between programming
and writing work.
And that can lure the maintainer into believing that with very little experience they're going to be a quick
and confident technical editor.
And a self-conscious maintainer can have them encounter with a writer and think,
I've never done this kind of work.
I don't know how to do it.
Like, let's not.
Or to defer to writers in ways that are maybe unhelpful for the software itself.
And the idea that comes up in this way is when a maintainer thinks that I don't have time for
documentation.
And that means the software project as a whole doesn't have time for documentation.
So whatever direction this cuts, it is natural.
maintainers typically have more extensive development work than what we might turn,
docs or product work.
And that makes me two problems too, which is outward looking.
So this is quite similar to problem one, but it's when a maintainer fails to
inquire about or recognize in tech writers and other collaborators kind of coming from
maybe different disciplines their capacity for their time to do work.
They're skills.
What things that a tech writer knows and doesn't know.
The assets.
What does this person bring to the software project from their kind of world of expertise?
And avenues support.
Who else are they bringing to this party?
This also cuts into directions.
That's own underestimating phenomena.
For instance, one might assume that a tech writer doesn't know how to use Git.
One, you can have the course of knowledge where you're so familiar with your problem
domain that you have someone coming new into some work.
And you assume that, oh, well, only the basics.
And the basics is so far beyond, you know, kind of the average first off the sheet knows.
Another example of this is when.
Like, I've seen a tech writer like I bring with me a lot of tools and assets that are not in your source repository, right?
I have templates.
I have weird tricks to produce documentation.
And that's something that's maybe invisible unless you ask about it or I share about it.
Again, whichever direction this cuts has like over underestimating.
This is also not unfamiliar.
It's a natural outcome when writers are pretty infrequent contributors to free software.
And it's really hard to recognize what you've just never seen before.
And then there's the third problem which is when we maintainers, tech writers,
other collaborators together fail to link our collective strengths capacity interests to the projects needs.
So in an old school tech writing situation, you do this thing information plan.
This is very heavy weight planning apparatus for sorting this stuff out.
And the open source software world is tends to be kind of looser.
We don't do this kind of thing very often.
Or if we do do it kind of done poorly because we're just not accustomed to doing this work together.
And documentation is kind of an unloved area.
It's easy to look at your documentation and see nothing but gaps.
And then the conclusion you draw from that is, well, any documentation work must necessarily be filling some on that need.
Whether that's true or not.
This failure to link capabilities together and the products interest together is it is also a natural problem.
I'm kind of repeating myself here a little bit, but tech writers and link hangers don't do a lot of work together.
And so we don't do this. And if we do do this, it is through inventing a brand new process from scratch.
And why should we expect that to go well?
So in today, I'm kind of this question that is carrying you through this work is what if you could see yourself and your collaborators and your project plan clearly.
Again, earlier in the process.
And so we can start by taking stock of ourselves as maintainers.
We can have some questions like how much time do you have as an maintainer for docs work.
Is this in addition to existing responsibilities or is it not?
What are you going to sacrifice to do this work?
What skill plan regularly to this project?
Are you already in a habit of viewing code? Are you already in a habit of viewing docs?
Are you writing code? Are you writing docs? Are you doing project management work? Are you doing community management?
What tools do you use regularly? Do you already have an already familiar with Mark Down or Restructure Text or whatever you got?
Do you have a static site generator or a content management system? Do you have hosting for these things?
Are you already equipped with spell checkmenters for matters?
What documentation already exists? There's an area where a lot of underestimation happens where lots of people have rough drafts, notes, outlines, things that are actually published.
And I think those things actually do count towards the resources you already have.
And when was the last time you changed the documentation? What, what, what, what, what didn't go well?
And what do you tell you to work on? What's going to have that motivation to bring that work to completion?
Then we can kind of direct these kinds of questions outwardly. Two are would be collaborators.
So let's ask some questions of our tech writer here. Right? How much time does the tech writer have?
Is this a brief consultation? Is this someone who's going to take up residence in your documentation?
What skills do they use regularly? Are they more of an editor? Are they more of a writer? Do they like to play with the tools?
Or do they like to play with the words?
What tools do they use regularly? Are they already using Git?
A little salty thought.
When was the last time the tech writer changed the documentation?
I think there's a world difference between someone who has submitted a typophics to your project,
then has not looked at your project before.
And that gap is like, doesn't seem that big, but it is enormous.
What are your tech writers? What are you excited to work on? Again, what kind of motivation are you bringing to see this work to completion?
And then we can talk about making a plan that is focused on where all this stuff meets.
And so when we take all that stock we've done.
And we are going to find the intersections of maintainer time, skills, tools, experience, interest,
and user needs.
And then we start looking for gaps in the plan.
Where don't you in the writer quite neat? Where don't you and the projects needs?
Not quite neat.
And where you find those gaps, then you can start to see ways to mitigate that.
So you can look to who else in your community can help you bridge those gaps.
Now these questions are fine. If you are thinking about them, you are already well ahead of most people thinking about documentation.
But now that I've said through this, you might have noticed a little bit of a problem here.
This is a super abstract.
I want you to make lists of things about documentation in the abstract.
I don't know.
Besides, it's super uncommon to have a writer just show up for no reason.
My story as a university student, that's a never event for an open source project.
Instead, what you probably have are specific things you want to achieve with documentation.
And now you need a collaborator to help you achieve those things.
And you have to recruit someone into the process.
So now we have to think about these questions in terms of a hypothetical collaborator.
This is a really, really hard problem, and I don't think you should do it.
So instead, it's like invert this intellectual exercise.
What happens if we start with a documentation problem to solve?
What does solving that problem look like?
And then what is solving that problem look like?
And then what does the actual project that brings that solution into the world look like?
That's like a plan.
So what resources would you need? What collaborators would you need?
What are the deliverables for that work?
How do you know when you're ready to start? How do you know when you're really finished?
What if we could order off the menu, seriously?
So, the way to this talk is to, is that I am excited to preview a work in progress that gets us closer to that ideal.
Let's call it documentation project archetypes, and it's a field guide to open source documentation work.
This work is, this is like documentation for anything documentation.
It's being funded by Google Season 2.
So, big thank you, Aaron. I think you're here.
Thank you Aaron.
And so through research interviews with open source maintainers, with tech writers,
who have contributed to open source and through hard one personal experience,
I found 18 types of documentation efforts in open source free software.
And right, I'm letting brief guides to cover the dozen or so most important.
I've broken them down into a few somatic areas, given each one a dramatic name,
and I'll give you a few examples and take you through one of them specifically.
So the first, the somatic area is planning and evaluation.
This includes projects such as the audit, where you inventory and evaluate what assets you are,
what assets you already have, the discovery, where you do a vertical slice of documentation work
to validate or de-risk larger effort.
And the study, where you do user research to find out what the users of your software need from the documentation.
There's this production theme, which is actually producing new documentation.
Projects in this category would be the manual, where you're writing linear prose documentation,
or the sample where you're producing sample code and demos.
There's revision and transformation.
Projects like the curb cut, where you're doing accessibility remediation, adding all text things like that.
Or the translation, which is internationalization and localization work.
There's the tools and process area.
So the factory, which is automating docs production, things like generating API references.
And the migration, where you move from one tool to another that presents documentation to your audience.
And so that's the one I'm going to look at closely here.
So each archetype comes with a short breakdown of what makes that project distinct.
So what is the migration?
We're going to start with a name and synopsis, briefly describe this thing in a sentence or two.
And to give you the key words to recognize later on when you are doing migration work,
that when you hear upgrade or replot forming or porting or retooling, that this is potentially the migration in action.
Next is the audience.
Who are you meant to serve by doing this work?
To the migration, it's a little complicated, but it might be delivering pages faster on page load.
It might be improving the editor experience.
So you can produce more docs faster.
When and why?
So what problems does this kind of documentation project address?
What problems does this documentation project not address?
Tasks and deliverables, or how you will know when you have finished the work.
Key people, who is going to do this work?
This is almost never just one person.
You know, even if you have a writer producing lots of words, someone has to read those words.
You need doctor viewers.
If it's a very well-researched project, you might have lots of support roles involved,
to do hiring and payments.
So you'll need HR and finance and legal and that sort of thing.
The last major section here is going to be risks to consider in your plans.
These are the hazards most strongly associated with this kind of project.
So for the migration, it might be trying to fit in rewrites or redesigns while you're also doing the migration way.
And so this is to give you the opportunity to make mitigation of those risks part of your project plan early on.
Now, I know this is not the whole story, and this means that each archetype ends with links to more resources about that project type.
Now, maybe this is still pretty general.
I'm still kind of asking you to draw the out.
And some of that's intentional.
I know you already have your own project management practices.
You're in community norms around how to do work within your software project.
But I'm really trying to help you to, like, prime you to start these conversations
and to be opportunistic about the resources available to your project.
By being aware of the different kinds of docs work, you can take advantage of your own time when you're motivated to do documentation work.
Or encouraging existing contributors to scale up their participation from one-off tasks to large projects.
And to advocate more strongly and make better use of major resources that you can get for your project, such as grant funding or co-workers getting involved.
Open source programs and other avenues that direct really big meaningful resources to your open source software and your documentation.
So, if you will have one of all this work, you can go to dbt.com slashvastem.255.
There's a rough draft of the migration archetype and some information there about how to keep up with this work and to give some feedback.
And with that hope, I hope that I have finally put the rest of the ghost of that very early project in my career.
And I hope that we can do more to make some docs together.
Yes, the question is in my familiar with pattern languages.
Yes.
I'm blanking on the name of the author, but there's a famous architecture.
Yes, Christopher Alexander, famous architecture book.
It's really fascinating.
I highly recommend it, even if you have no interest in architecture.
It's a fun thing to you can turn to a random entry and see a description of like a potential solution to a potential architecture problems.
Yeah, I have not made the explicit connection here, but now that you mentioned it.
Yeah, that's definitely an influence.
Because also in the intersourcing community, they have explicitly taken all pattern languages as a way to spread patterns in the community for how to teach or how to find patterns that work to get stuff done to change your community to do better work.
So, this is very, very similar.
I think you have a look at the intersourcing community, because I actually have a library of patterns on it for doing intersourcing.
There's probably some books back there.
There's the intersource comments and also the open practice library.
It has a, yeah, and I know there's some other resources along these lines as well.
I've, I'm blanking on names now, but like there's, there's a lot of stuff from like the UK government, like GDS,
and there's some stuff from 18F, US governments that kind of like has a kind of playing card format.
And so yeah, I'll update this page with some links to some of that stuff as well.
But yeah, it's a good, good shot there.
And the second quite well full of questions.
This is not only irrelevant for the source projects, it's not just open source.
I mean, that's like, it's nice to have creative constraints.
And yeah, I think there's a few, and I've taken some notes on, and I'd like to embellish on later, perhaps, of projects that are kind of more corporate in nature and, and I kind of thing.
And I think, yeah, I think there's, there's some stuff at the periphery of this as like a explicitly open source kind of resource.
And, and there's actually grew out of some work where I was trying to describe like tech writer archetypes, like the kinds of people, like what the, the kind of modes of working that as tech writer, I've seen.
And so I think, I think there's lots of opportunities to grow on top of this work.
Thank you so much.