How you write matters in open source
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Number of Parts | 43 | |
| Author | ||
| License | CC Attribution 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor. | |
| Identifiers | 10.5446/67118 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
FOSS Backstage 202429 / 43
8
11
00:00
Context awarenessCodeBitOpen sourceArithmetic progressionTelecommunicationPresentation of a groupMusical ensembleForm (programming)Projective planeComputer animationXMLLecture/Conference
00:46
SoftwareDigital photographyProjective planeTwitterBlogPresentation of a groupSoftware developerNeuroinformatikDistribution (mathematics)Open sourceMereologyPoint (geometry)WordIdeal (ethics)Lecture/Conference
02:04
Projective planeAnalytic continuationOpen sourceOpen setNumberLecture/Conference
02:33
Open sourceProjective planeNumberOpen setPoint (geometry)FeedbackLecture/Conference
03:02
CodeOpen setWritingLogicProjective planeBitSource codeOpen sourceTelecommunicationMultiplication signVirtual machinePerformance appraisalInformation securityGoodness of fitLecture/Conference
04:18
TelecommunicationOpen sourceProjective planeMultiplication signTelecommunicationGoodness of fitCodeOpen sourceQuicksortRight angleWebsiteWritingAbstractionDifferent (Kate Ryan album)SoftwareDirection (geometry)BlogSource codeLecture/ConferenceProgram flowchart
06:11
WritingOpen sourceSoftwareData structureService (economics)QuicksortLecture/Conference
06:36
Open setIntelligent NetworkSoftwareData structureProjective planeDifferent (Kate Ryan album)Open sourceService (economics)Control flowWeb serviceMixed realitySound effectLecture/Conference
07:06
SoftwareLatent heatTerm (mathematics)Service (economics)Open sourceType theoryDifferent (Kate Ryan album)Limit (category theory)Sound effectWritingBitLecture/Conference
07:43
View (database)Point (geometry)SoftwareMereologyMixed realityProjective planeDataflowDisk read-and-write headLecture/Conference
08:36
WritingProjective planeBitProduct (business)Figurate numberFamilyBlogAssociative propertyRight angleElectronic program guideSimilarity (geometry)PressureCollaborationismLecture/Conference
09:57
Right angleElectronic program guideDifferent (Kate Ryan album)PressureProjective planeSelf-organizationSimilarity (geometry)Lecture/Conference
10:29
Exception handlingPoint (geometry)WeightComplex (psychology)Electronic mailing listElectronic program guideBookmark (World Wide Web)Right angleBitLecture/Conference
11:11
Self-organizationElectronic program guideMatching (graph theory)WritingCodeCategory of beingElectronic mailing listThermal conductivityTerm (mathematics)WordProjective planeInclusion mapContext awarenessView (database)NumberDifferent (Kate Ryan album)Type theoryPoint (geometry)CASE <Informatik>Formal languageLecture/Conference
12:53
CodeTerm (mathematics)Inclusion mapPersonal digital assistantInteractive televisionMereologyContext awarenessTerm (mathematics)Standard deviationProjective planeLecture/Conference
13:36
FeedbackMereologyData conversionElectronic program guideInclusion mapProjective planeOpen sourceTelecommunicationMultiplication signType theoryLecture/Conference
14:44
TelecommunicationFeedbackElectronic program guideLecture/Conference
15:08
Software maintenanceFormal languageBlogFormal grammarCASE <Informatik>Sheaf (mathematics)Exterior algebraProjective planeWordStatement (computer science)Point (geometry)Context awarenessMultiplication signWebsiteEntire functionMereologyComputer animation
17:19
Set (mathematics)Statement (computer science)Projective planeSoftware maintenanceMereologyInformation securitySoftware testingLeakSemiconductor memoryDegree (graph theory)Lecture/Conference
18:15
Projective planeSlide ruleObject (grammar)Game controllerBlogRight anglePlanningLecture/Conference
19:04
GeometryProjective planePoint (geometry)Auditory maskingMultiplication signMass
19:32
WebsitePoint (geometry)Projective planeArithmetic meanLattice (order)WebsiteIdentifiabilitySound effectContext awarenessDifferent (Kate Ryan album)Information overloadDegree (graph theory)Statement (computer science)Term (mathematics)Open sourceMultiplication signFormal languageDigitizingSet (mathematics)Web pageRevision controlLecture/ConferenceXMLUML
21:29
Web pageMultiplication signDifferent (Kate Ryan album)Variety (linguistics)Context awarenessTerm (mathematics)Projective planeBitContent (media)Open sourceFitness functionFormal languageWritingWordLecture/Conference
22:32
Projective planeSoftware maintenanceWritingElectronic program guideContent (media)InterprozesskommunikationTelecommunicationLecture/Conference
23:15
Projective planeSpeech synthesisLatent heatBitDecision theoryLecture/ConferenceMeeting/Interview
23:51
Speech synthesisProjective planePerspective (visual)Presentation of a groupPosition operatorLecture/Conference
24:25
Open setMultiplication signView (database)Point (geometry)Lecture/Conference
25:09
Right angleProjective planeRevision controlOpen sourceWordLecture/Conference
25:51
Formal languageWordLine (geometry)Right angleFraction (mathematics)Lecture/Conference
26:23
Formal languageFraction (mathematics)Multiplication signContext awarenessWordLecture/Conference
26:51
Projective planeTerm (mathematics)Different (Kate Ryan album)WordArithmetic meanLink (knot theory)QuicksortContext awarenessCoefficient of determinationGodPoint (geometry)Meeting/InterviewLecture/Conference
28:13
Multiplication signWritingQuicksortFreewareEscape characterBitProjective planeInformationMeeting/InterviewLecture/Conference
29:05
FeedbackProjective planeArithmetic meanLecture/Conference
29:33
Musical ensembleConnected spaceLecture/Conference
Transcript: English(auto-generated)
00:07
Hi, I'm Kyle. I work for the Bottle Rocket project at AWS, and I'm going to talk to you a little about writing in open source, not necessarily writing code, but human communication in the written form.
00:22
So, basically, what I'm going to go over is the background and context of this presentation, some overarching ideas, and then we'll do kind of the practical lessons learned, and that'll be kind of interactive, so I'll probably be asking you to kind of raise your hands or say something towards the end of the presentation. So, just before we begin, I will tell you a little bit that writing and people are always
00:44
works in progress. I say that because you might look at some of the things that I've done or some of the words that I say, and you say, well, that's not exactly what you are expousing here in this presentation, and that's okay. We're all developing and trying to trend towards that ideal that you want to get to, and I think that is especially pertinent in writing,
01:05
especially when we're doing things in open source where we can always make changes, so I do want to get that out of the way, but my personal history in this, I've been writing software as long as I can remember. There's photos of me as a tiny kid like in front of a computer, and then I started writing software at some point as a kid,
01:21
and I've been doing it ever since. How I got involved in kind of this part of technology is interesting. About 15 years ago, I started writing blog posts because, when I didn't understand something, and I couldn't find anybody else who had written about it, I wrote something about it. Eventually, I started writing everything that I figured out, and a particular
01:41
piece of software said that's really great. We would like to give you money for this, and I said that's a thing? Really? Someone will pay you to write about stuff? So that kind of put me on this road to getting me to be a developer advocate. So, with that, I now work for the bottle rocket project which is a container optimised Linux
02:00
distribution, so if you want to run something for Kubernetes, you can use that in your worker nodes. I won't get into it but you can see our nice logo on the side here. Where this project and this narrative starts is on the previous project that I worked on. I've worked at US for a number of years, and I worked on the open search project. Their booth is out there. You should go out and talk to them. They're great people.
02:23
I was there when it started, and open search was kind of interesting because it was born out of a continuation, a fork of another project to keep it open source. It was really interesting because that was when it was at the centre of some tech news. So, the open search project and
02:41
what became that was something that everybody was writing about for a number of weeks. My role in that project really was to talk about what was happening because at that point, it hadn't become a fully licensed open source project. It was something that was an idea, and I got feedback about how we were writing about it. Now, we had always had the intent
03:02
to make it open source, and then I had people come to me and say, we really don't like the way you're talking about this open source project. I had to do some kind of self-evaluation and understand why. I think the intentions were great, but then on top of that, what we've done is taken what I learned in the open search project and now I work on the bottle rocket project and we've applied that in a more systematic way. I want to tell
03:24
you my experiences about that and my opinions on it. Hopefully, you can use them to help you write better in open source and write in a way that is more inclusive. So, let's talk a little bit about open source and what it means as far as writing. Now, if you were to create a magical weighing machine and took all the effort that you would have
03:43
in any given open source project, you might be surprised by what time is spent on. My intention is to say that time is actually spent more on like writing and communicating with other humans than it is actually on source code. When you think of this, you think about documentation, but that is the tip of the iceberg. You have things like
04:02
pull requests or merge requests where you're describing something. You have things like issues where a user is describing something they found or maybe a security issue. You have code comments which are in the source code but they're human communication that's written, not logic, so that's something that takes a lot of time, and good projects have
04:21
lots of code comments. Policies have to be written, and those take an inordinate amount of time to get right and a lot of communication back and forth. You have things like your project site where you're talking about things in the project. You have things like blog posts which take a lot of time to also put together where you're describing maybe uses
04:41
of things. You have things like talks where you have to write abstracts like I did for this or the talk itself. You have release notes where everybody is every time you release software, you're describing what is in that, and then you have things like design documents that take a huge amount of time to describe the technical direction of things. If you take all these, and this is not even there's much more, you're going to start realising that the
05:04
source code is that's a considerable amount of time but there's also a huge amount of time that goes into the written communication. So, with that, you have to consider what is going on with that. Functionally, writing in open source is different. Marketing copy will not
05:22
fly in open source. If you've ever looked at something and you go, wow, that doesn't look like it makes sense, a lot of times, it's something they've taken and took some marketing copy and tried to use it in an open source project and it just looks wrong. The reason is the goals are different. Marketing copy is generally there to sell you something or to get you to do something that evolves some sort of exchange.
05:45
Open source doesn't have that. The goals in open source might be to get a contributor. That's not selling something to somebody. The relationship is different as well. The way you find out about open source projects you care about might be a dependency. You never even actively chose that, right? When people are talking about this, you have to describe it in
06:01
that way. Then it's not the same as writing for internal writing either, so stuff that you might find inside your company, that's a very different way of writing too because functionally there, what you're doing is writing to a known audience with a known kind of structure, and you won't be able to do a pull request on a company policy
06:20
very often. Maybe in some radically open companies you might be able to but that might not be a thing to do a pull request on some sort of company policy. So, it's very different. Even when you talk about software itself, services are a different way of writing as well. When you have software as a service, which I work for Amazon Web Services,
06:44
and that's services in the name, there's a different kind of structure that exists. There is an understood clear relationship in services between the people who are using the software and those who are providing it. That breaks down when you start bringing in open source projects into the mix. It's very different. In effect, what I'm saying is
07:04
you have to kind of look at these things in a way that are showing how different they are. Even with software as a service, the specificity of use is something that is implied. You might have terms of service that limit that. Open source software, we want people to use things
07:21
in crazy ways. There is no kind of like you have to use this for one particular use. So, when we take this all into effect, we have this different type of writing that might be foreign for a lot of different teams. You have to find the right way of doing that. Let's talk a little bit about some overarching ideas about
07:43
writing in open source software. These are ideas that have come to my front view by looking at the different pieces that I've worked with in the past. It comes down to a few different things. The first part I want to talk about is voice.
08:00
What is voice? I like this definition. It's a rhetorical mix of vocabulary, tone, point of view, and syntax that makes phrases, sentences, and paragraphs flow in a particular manner. If you've ever read something written by someone you know and you hear their voice in your head, like that is a very strong voice that they have, but it can mean other things as well. Projects can have voices. So, for example, you have a consistent way of writing
08:25
about a project that might have some descriptors to it. In the bottle rocket project, we try to write very matter-of-factly and empowering but I've worked in other projects that have a very narrative way of speaking about things, and they have almost a rebellious tone. If I was to move those around between different projects, it would sound off. It wouldn't sound right.
08:44
So, not only does a project have that, the individual has their own voice as well. This gets tricky when you're collaborating. If you have a very strong individual voice, you try to collaborate on a document, it's going to sound disjointed when other people try to bring in new paragraphs that are not in that voice. So you have to figure out the right
09:02
way to balance those pieces. So, in named writing, for example, like a blog post that said written by Kyle Davis, Kyle Davis' voice is going to come first, but the project voice still has to exist. If you're talking about documentation or release notes, it shouldn't sound like it's coming from Kyle. It shouldn't sound like it's coming from the project.
09:24
The other thing I want to talk a little bit about is style guides. Incredibly important, but don't write your own style guide. It's probably the biggest mistake that you can make. These are really time-consuming to write well, and you should find somebody that is something similar. So, Bottle Rocket uses the OpenStack style guide. We are not in any way related to
09:43
OpenStack or the OpenStack family of products or projects, but it's familiar enough to us that we can really use it. The other thing to look at is that you shouldn't really try to adopt something from an associated organisation or feel that pressure. You might
10:00
say, okay, well, this project came out of AWS, so we are going to use the AWS style guide, right? That might work but it might not because you have different goals. That's why we ended up with something totally different. You have to look at that. For example, when we were talking about Bottle Rocket using the OpenStack style guide, that works because they're kind of similar
10:22
projects. If I was to try to use the WordPress or the Blender style guide, it probably wouldn't work because we are talking about containers and infrastructure and things like that, and they wouldn't have the right kind of metaphors and tools in those style guides. You're going to have things when you adopt another style guide which are your exceptions
10:41
to those style guides, so the complexity of those style guide exceptions is something you have to consider. If you have a big long list of exceptions, we use the OpenStack style guide except for these 25 points, is it the right thing to do to have 25 exceptions on it, or should you find something that matches a little bit better? This is my favourite one for style guides is don't expect anybody to read it at first.
11:06
This is where I really put a lot of weight on it because what's going to happen is you're going to have people write something, somebody's going to review it, maybe it's you, maybe it's someone else, and then you're going to say this doesn't match our style guide and they're going to say what is that? Then the next piece they're going to have internalised
11:23
that style guide and then they will have a lot more workable first copies. So, a lot of great stuff on this. Now, where we get into another piece that I think ties into the style guide in an interesting way is naming terms and inclusion. This is
11:40
something that I've had to deal with in a couple of different ways. It is really complicated to navigate. What you should be doing on this is finding the correct concrete guide post to help you navigate this particular issue. When I say naming terms and inclusion, there are a number of terms that maybe don't work out in the public context or maybe they're
12:03
outdated or things we've decided to move on from language. One place I look to is inclusive categories. You can help find and navigate your project that way. There will be other places as well. For example, your code of conduct will have potentially words that you do or don't use
12:23
in your project that helps you be a more inclusive community. There will be other places as well. Sometimes, you know, blinters out there for this type of writing do have these names included in them. When looking at terms and inclusion, one thing you really have to do is
12:41
look at how they work with your corner cases in your community. For example, sometimes you will have a dependency that has a very different point of view on these terms, and you have to figure out beforehand where you're going to interact with those, how do you describe a term that they use regularly and you can't really use because it is something you've decided is not healthy for
13:02
your project. The other thing to remember here is that we live in a global world. I've and every different culture is going to bring its own baggage to the plate here, and they're going to have different standards for it. A lot of this is about education and being
13:23
maximally inclusive in your community, and sometimes people don't understand that, in a different context, you may be excluding people, so it's a really important part of this is to understand how to navigate the different global contexts that are here, and there are sometimes a lot of tricky conversations that have to happen around this. All right. So, feedback.
13:48
This is a really tricky part about writing because a lot of times in open-source projects, you're accepting written communication as pull requests or some type of other contribution, and if you have set up your project well, hopefully, you can make this a very neutral
14:04
way of providing feedback to those users. If you don't, it can really be looking like Kyle doesn't like your writing, and that is not a place you want to be. Where you want to have is those concrete guide posts, either from your style guide, from your naming and inclusion guides
14:20
that help you take the Kyle doesn't like this or whomever is reviewing it doesn't like it and put it into something else. The great thing we have here is that a lot of what we're doing is actually things that are like linting, right? Like, we're pretty used to getting things from
14:41
linters and getting that feedback automated ways, and that is pretty useful that a lot of people in our communities are already used to that. And be crystal clear on who is saying what. This can be something that can be tricky because, you know, if you are providing that feedback, you need to make sure that it is the feedback between what you are saying,
15:05
maybe you're providing some guidance on it, but also there are things in the style guide that may be non-negotiable. I want to do in this section some practical lessons learned, and I'm going to read to you a few different cases that we've seen in our community.
15:21
These are individual sentences, and then what I will have you do at the end of these three kind of phrases, maybe you can tell me if you know what the problem is with these sentences. Practical lessons learned. Here's an example. We are excited to announce the release of 1.0.0 in a blog post. That's the first one. The release of 1.4.0 has been delayed. We
15:45
decided to focus on something else on the project site. Thank you for your contribution. We will review it and get back to you. Does anybody know what the common maybe problem point between those three statements are? Anybody? Who is we? That's great. We is a really dangerous little word in the English
16:07
language related to us and our. It's a plural first-person collective pronoun. You're coming to a talk about grammar. You didn't know that. We is particularly problematic in English because there are six different ways you can use it.
16:21
I'm not going to go through them because they require a lot of examples. At the heart, they are ambiguous for the most part. When you have we in it, it's really hard to parse out who it means. Is it clear who you're speaking for? Are you speaking for the whole community? Maybe that can be pretty problematic. Are you speaking for
16:45
maintainers or yourself and you're using the royal we? It's not very clear very often, and you have to put yourself in the seat of the reader sometimes to understand where it's coming from. How do the alternatives work here? Speak for yourself. Sometimes that's very difficult for people to do. Saying I believe something is so much harder than saying we
17:04
believe something for whatever reason, but encourage people to speak for themselves in all contexts where they're doing that because they don't want to speak for the entire community. Then define your antecedent. If you're not careful, defining an antecedent can sound like you're doing a policy. We, the maintainers of BottleRocket believe ... but there are a lot
17:24
trickier ways of doing that where you're making it abundantly clear to the reader what it means. You should have that litmus test to read through and say have I defined what this means? Next set of three. BottleRocket believes that security comes first.
17:45
Issue 467 suggests a memory leak on an issue. BottleRocket says to Kubernetes, I'm ready in documentation. Can anybody identify the problem with those three statements? Go ahead. Is it the whole project? That's a good part of it.
18:04
There is one thing that overarches all of this, and that's anthropomorphism. This is something when I was in my master's degree that my master's advisor would say don't ever do this, but you're assigning human traits to non-human objects. If we take a look back at that, I will go back a couple of slides. BottleRocket can't believe anything. It has no brain. It
18:25
is a collective of people. Issues can't suggest anything. People and issues can suggest something. And Kubernetes, a BottleRocket says to Kubernetes, I'm ready. Is the BottleRocket
18:41
project talking to the Kubernetes project or is a BottleRocket node talking to a Kubernetes control plane? It becomes very complicated. One of the things that you can often see here is when projects and companies have the same name, it becomes super unclear when you start anthropomorphising. It's a really tricky thing. There was a blog post that came out
19:04
a few weeks ago. I'm not going to name which projects they were involved in, but it became a big deal because they were anthropomorphising the project and it became very contentious very quickly because there was that overlap. Oftentimes, this masks technical details in ways that you don't want to do. The BottleRocket says to Kubernetes,
19:25
you know, that's not being very clear to your users and then people can confuse what you're meaning with that. And then how do you fix this? Point to a person than a thing. The example with the issue. The issue isn't saying a thing. The person is saying something.
19:43
And be more precise in your details. However, that might come about, right? So it can be if you're meeting projects, you may have to say the BottleRocket project has a document that says X, Y, and Z. Okay. Another set of three and then we will wrap up.
20:01
Supported characters are digits 0 through 9 and A through Z in the documentation. The following versions are no longer supported, and the following vendors provide support. Can anybody identify what is going on in those three statements? No? Okay, go ahead. She said those are three definitions, different definitions of support.
20:27
Yes. That is what we call an overloaded term. This is incredibly common. One term has multiple meanings based on the context. This came from one document where we had support meaning seven
20:40
different things in a matter of three paragraphs, and it can be really, really hard to understand. There can be other terms too. I'm not just picking on support. That's something for our context in open-source projects you should really think about, so what does it mean for your particular context? This has an incredible effect on those who have a high
21:04
degree of fluency in the language that it is there. As people who are highly fluent in English, you might easily parse out what support means in any given context, but someone who has been speaking English for a much shorter amount of time might have a higher difficulty there, so you're really kind of excluding people inadvertently by using these terms very loosely.
21:24
This often only reveals itself in context. On one page, if you have, let's say, a project site and it says support once, you can probably quickly parse that out, but on multiple pages, it can be very complicated. How do you fix this? A great exercise to do when you start identifying these terms is to try to find replacement terms that work in a variety of
21:44
context and then sub them in. It can be really tricky. You will start to realise how hard writing can be when you're trying to write for people of varying different fluency in English or whatever language you're targeting, so actively pick those terms that might fit it
22:01
a little bit better. It was a real challenge for us to unwind what the word support meant in our project. To wrap up, there are four things I want you to take away. Style and content are not portable, so you can't just take content from one place, copy and paste it into another place, especially in open source. It's not going to work very well. You're probably going to end up confusing people along the way. You have to relentlessly pursue clarity. Every time something
22:26
is written, you need to make sure and ask yourself, is this clear from a variety of context? You have to actively disambiguate constantly in your writing, so it may seem a little unnatural to define antecedents, it may seem a little unnatural to define what you mean by
22:42
the maintainers of your project versus the overall contributors, but it is important to make sure it is accessible to everybody. And then have guidance over guiding as an individual. That will give you those concrete guideposts to help anybody contribute to your project for written communication in a meaningful
23:03
way instead of it being the Kyle show or the whatever show of movers doing this and providing the editing for these pieces of content in your project. I think we're ready for Q&A. Anybody have questions? I have a question about when you're speaking on behalf of a project.
23:31
I have chosen to do that before for not being a target specific. That's why, could you clarify a little bit more, how would you put yourself as an individual
23:45
without becoming a target and people thinking your particular decision? That's a good question. When you're trying to speak for yourself as you're in an individual project but you don't want to be the target for maybe somebody who doesn't want to have really positive outcomes out of this,
24:05
it can be tricky. From my perspective, sufficiently putting that, you know, I'm speaking for myself and this is my personal belief on something. Others may also believe something else. I think one of the earlier presentations
24:23
did a great way of doing it. I think Ruth talked about I'm 3 out of 10 on this particular opinion, giving how strongly you believe in something and leaving room for others to have other opinions. That way you're not just making it you're the person who's the mouthpiece for something and
24:42
then all the ire for that goes directly to you. You've left an opening. That's my point of view. I've come into it a few times. It's tricky though and it's more contextual than probably we'd like it to be. Other questions? Yep.
25:07
You talked about writing that is globally inclusive so that you don't exclude particular people. Can you give us an example to illustrate that? Yeah. The support example is a great person, a great example of this. We had a person in our community that read through the
25:23
document and came away with how we were using support indicating that we were providing support in an open source project when we were talking about the support of a particular version. So they thought if I was using the current version then I could contact somebody about
25:42
that even though the license said it was as is. What it really made us do is step back and say that person who came from Japan had a different understanding of what the word support meant and they went over the line for what it meant. We really had to go back and say, okay, how does this look if we were to really be more precise with our language,
26:05
right? I think it was reasonable to think if you looked at the word support in paragraph one and support paragraph four, it confused people. So with that, I think it's making sure that you're using not language that is lowest common denominator but using language
26:24
that's precise, that would have a hard time being misunderstood. I think that's where you kind of like become more globally inclusive, right? If you're just talking to a bunch of people who have spoken English for 30 years, people are going to get more out of context.
26:47
I have a quick question I hope. So when you talk about being precise with words, and support is a great example, that works for one project but our users and members are opposed to so many projects defining their own terms. So how do we deal with that?
27:05
Yeah, that's tricky. We do have a glossary in our project that says this is what we mean by various different terms in the project. One of the things that is unique about Bottle Rocket is we name things after dog breeds. So we have things called Sheltie and, you know,
27:24
there's one we're talking about right now is Pug and, you know, all sorts of different things like that. And that can be really weird when you don't know what that means, and it might have different meanings other places. And if you provide sufficient links to those pieces, it makes it a little easy to kind of unlock what that meaning is.
27:41
Sometimes it is just maybe over linking those things in the pieces that you're talking about. Because if someone's coming into it, we've all heard the example of kind of technobabble where people have these really strange words that have zero meaning outside of that context. So you've got to provide that kind of context over the top, because you've got to remember
28:01
somebody can come in at any given point and they could be confusing what Pug means in a different project. So the glossary is where I'd kind of unlock that. Sort of the easy way to react is to make things longer, to explain, to add sentences. I love parentheses. My writing is too many parentheticals. How do you do that without
28:23
exploding and expecting people to read treatises about what you're saying? Yeah, it can make things really long sometimes. Other times you can kind of provide asides to it. We actually extensively use footnotes in our documentation in some of the pieces that we write to kind of give people that I don't understand this way to kind of get the escape
28:45
hatch. It can mean linking as well. Those are kind of free from a linguistic standpoint that it can make it flow very nicely. But if you have something, even parenthetically, more information on this project, it will give people a place to go for it.
29:03
I would rather err on the side of being a little bit more descriptive. So if anybody comes in, they see it. But when you want to keep it smaller, try to provide linking and then providing feedback on that is also great too, because somebody who does the majority of writing for a project, it's easy for you to do. But when you're talking about somebody who is writing
29:24
something new, you can say, what does this mean? Can you link this? That provides a lot of places for it to be a more instantly understandable document. Alright, thanks. That was it. Thank you very much, Kyle. Connect with me.