 Okay, so I've given an iteration of this workshop before as a session, and I've also given an iteration of this as a longer presentation. I do have a bit.ly link down here at capital D-C-E-U hyphen in the lowercase writers workshop. That's if you want to follow along or maybe tomorrow or next week, you're thinking about some of the prompts we do and you want to look back and look at that. You can use that link, and it's fully accessible, all the alt tags are on there and all that kind of stuff. There's images in my deck, but most of them are decorative, so for brevity I'm not going to describe the images unless they add more context to the conversation. And I want to give a shout out to Margie Freeman who wrote this with me. This is actually an iteration of the diversity speaker workshop in the WordPress community and we changed it to the Drupal community and then we changed it to be a writer's workshop, so I just want to give the credit where credit is due. So Jill Binder helped us move that space from the WordPress space into this space and then Margie Freeman who worked with me at Red Hat really put a lot of work and made it a really beautiful slide deck. So we lost a community member last night. I'm not sure if anybody knows Hawkeye Tender Wolf who works at Lullabot, but he passed away last night, so I want to give a little moment of pause to think about him and if you knew him, you knew him and he's a pretty special person. So my name is Amy June. All one word, title, camel case, never Amy, never June, always Amy June. And I go by Volkswagen Chick across all of the social media spaces and by all of them I mean LinkedIn and Mastodon. I recently picked up a job at the Linux Foundation. I'm on their certification team, so I helped build certifications for emerging technologies and I was on the editorial team for open source.com before this and this is why I give this workshop is because as an editor or someone who enters content into a Drupal site, some of these things will really help your editor because technical writing isn't about rainbows and unicorns and sparkles. It's about getting the information out there in a way that's easy to digest. So anyway, yeah, work for the Linux Foundation. This is my cat spot and he's on here because if there's any typos, it's probably because he ran across the screen or something, so we'll just blame any typos or things. He's a really good guy. He likes to go outside and he drools a lot. It's kind of cute. You ever see the movie Hooch where the dog drools and then does this? He does that. He's an interesting cat. Okay, so why this workshop? What I want to help you do is I want to help you find your why because sometimes we need to know why we're going to write something. I want to help you find your what, what you're going to write about. Come on in. Then I'm going to help you find your words. So the why, the what, and the words of technical writing. And there's two aspects of technical writing that we're going to talk about. We're going to talk about technical documentation and we're going to talk about technical articles. This is sort of a roadmap of what we'll talk about. We'll dispel some myths about why we don't write or why we don't think we should write. We'll do a brainstorming activity together. Now, I'm going to ask people if they want to share their ideas as we go. You do not have to, but if you want to, there's no pressure, you know, just to sort of share what you're working on as we go. We're going to find the why, the what, and the words and we're going to use those five W's and we'll talk about what those five W's are. Again, two parts of it. There's technical articles and then there's technical documentation. And then if we have time, there's a section where I break down and we talk about the basics of markdown and why we use markdown when we submit articles, why we use markdown because it's portable and why we don't use PDFs and Google Docs. So that's if we have time because it's only, you know, what, an hour and a half slot. Okay. So why haven't you written? Does anyone, has anyone not written a publication before or written technical documentation? Okay. You don't have to answer the, the, the why part, but you know, sometimes people think that they're not an expert. That's okay. You don't have to be an expert. Everyone has an idea, a different idea of what expert means. No one knows everything and everyone has something to learn. And the, you could know more about your topic than your audience does. And so, you know, when we think about articles and we think about readme's and documentation, there's the beginner, the intermediate and the advanced, you know, and everyone has a different level of what they're looking for. People will ask questions or make comments on my articles and documentation and I'll look like a fool. This is a myth. People might ask questions or have comments that you can't answer, but that's okay. You know, you don't have to know the answer to everything. And your readers understand that not everyone knows everything. Sometimes people are worried that they, they don't have enough page views. They failed. You know, I wrote for open source.com. We would have an article that was super intuitive and super good, but it would have 58 views and we'd get a fluff piece that would have 600,000 views. And people would look at that and measure their worth. Well, you know what? If you reach three readers today or three people read your configuration and you read me, that's three more than yesterday. So that's a 300% markup. And you just enriched and bettered someone's life. So page views is kind of a weird thing. And then the last myth that we came across was some folks think that a how to is the only way that you can get your information across. So we'll cover some more formats of writing when we're talking about articles and blogs in the coming slides. So here are a few questions to help you think. And again, no one has to answer these out loud. You know, just kind of think about these as we go through these exercises of what kinds of things that you're worried about because all of us are, well, most of us are worried about something. Why haven't you written for something larger? Maybe you've written an article for your organization, but you haven't submitted an article for something like open source.net. Maybe you've written a read me in the contrib space, but not core. So why haven't you written for something a little bit bigger? And then if you've only written once, why haven't you written again? So why do we write? We write to share information. You know, we don't want to hold our information hostage. We want the world to know about it. Most of the time, us in open source, sorry, I'm tripping over this wire and I want to position a little differently. We want to promote our open source projects. We want people to know about Drupal. Remember in the Dries note yesterday, Dries talked about marketing. So writing an article is a great way, writing a case study, you know, converting that case study to a lightning talk, improving the read me so someone outside of our Drupal bubble can look at a contributed module and know what it does, except not just the name or who's the maintainer. You know, so it's really a marketing thing. And then it helps build personal brands online. You know, maybe you're an entry level front-end developer and you're looking for a different job. Well, you write an article that's something else that you can put on your resume. You know, if you write a read me, it's something that shows up on your Drupal.org profile. So it really helps build your personal brand. And then as you write things, you actually learn as you teach, you know, because you're researching and you want to do the best job. Well, we hope that we do the best job and so we learn as we write. And then also we write because the more rewrite, like say if you're from an excluded or marginalized community, the more people, the more lived experiences people see gives other people encouragement to write as well. So the hardest part about writing is actually starting. How many of you that blank page is like super scary, but there's resources to help. So before we get started, I wanted to give some resources for places that are great for first-time contributions for writing. I used to work for open source.com, you know, but we all know that red hat doesn't care about open source so that no longer exists. But there's open source.net where a lot of those writers have moved to. So open source.net is a wonderful place to start writing. But we also have some community run publications. If you're into sys admin, there's sys admin signal and there's an email address to get ahold of them, technically rewrite. He's not necessarily open source, but he loves articles about what tools you use to write. Drupal Camp Asheville, we have a neurodiversity initiative where we opened up knowledge sharing not just to doing presentations, but if you wanted to write an article. So we run articles for first timers or people who are too nervous to speak. And then of course we have the drop times that's new to Drupal. And you just have to drop them a line. So anyway, some resources of places that you can actually submit to and get published after this. Open source.net is new. It's the same as open source.com, but community run. I want to really tell you folks that it's building momentum. It's going to be great. So finding a topic. So we're going to move into sort of a brainstorming session because I'm going to talk a lot about different kinds of articles and different kinds why we write a certain way, but it's easier if you have a topic in mind. So we're going to do a brainstorming exercise. So if you have a notebook or a computer or a napkin, however you want to like kind of write some down, down some of these thoughts or keep them in your head. So the first we're going, I'm going to help you answer the question. I don't know what to talk about. I don't know enough to give to write. I'm not an expert in anything. If you've written an article before and you're just stuck on what your next article might be, we'll be looking into answering that as well. So the brainstorming is basically you pick up as many ideas as you can. We're not looking for good. We're not looking for perfect. It's just the good, the bad and the ugly. It's just getting all that stuff out there on paper because it might look ugly now, but in two weeks when you're looking at your notes again, you're like, oh, I really like that. Again, you can draw, you can do mind maps, you can do any format that summons inspiration. Also if you're new to tech, you don't, if you don't have some of these answers yet, that's okay. Maybe you can use these prompts to imagine what your answers might be later on. So what I'm going to do is I'm going to read a prompt and give you all some time and then read another prompt. So it's going to be like a little, just a little slow for a few minutes while we get all of our ideas down. So what is your favorite module or theme? What are some cool tricks that you use all the time? What's a really rad thing that you've created? Rad means cool. I don't know if that translates in other languages, okay. What was the last thing you learned or how did you learn it? That ties kind of into the next one of what would you like to learn next? Remember, we talked about how sometimes writing things is how you learn. So it helps that learning process. What do you want to learn next? What's the biggest challenge you've had with Drupal? And how did you overcome that biggest challenge? Or insert any open source technology there? How many times did you have to install that Linux box on your machine before it worked? And then not every article has to be super technical. So how has your past experience shaped who you are in your new role? People love a good personal story. Do you have any tips on overcoming the learning curve between versions of Drupal or insert open source project there? Any tips on the learning curves? How has AI changed the way you develop? This next one is sort of one of those insert your own mad libs. How is UX different from design, insert comparisons there? I think we have one more slide for the prompts. How does working cross functionally or what does working cross functionally mean to you? How does focusing on solutions help you with your career? And my next prompt is written awful and I look at it now and I'm like, oh, so please forgive me. Well, no, the second to next one is awful. How does being the only insert person role whatever in your class or your role affect your career path? So are you the only woman? Are you the only parent? Are you the only front end developer? How has that affected being the only one in your group? Again, people love those case stories and career stories. And here's the really poorly written one. What open source technologies outside of Drupal do you use? That was a lot of words for not a lot of content. Oh, I guess there is one more slide of brainstorms. What was your first role in tech and how has it shifted? Talk about the path of where you are now versus where you came in. So I'm a hospice nurse by trade, but here I am giving a public speaking, you know, thing in open source. So how did that happen? And sort of tangentially off off of that, do you have tips for career shifts and moving roles in tech? Did you move from being a project manager to a developer or the other way around? What learning curves did you have? What are some tools that you use to help with task management? Everyone loves a good story on what keystrokes you use or what program helps you save time on your work day. And then the last one is think about the first time you contributed to open source, you know, whether it be a code in the code base or a presentation or in a forum. Why did you do what you did that first contribution? How did the first contribution make you feel? Because that goes along the lines of the tree's note yesterday, too, you know, the marketing and the telling of stories. And the more we tell our stories about contributions, the more contributors will draw in from other places. So again, I don't make anyone share out loud. But if you want to, you can. How did that brainstorm feel? Does anyone have any ideas that stuck out to them that they'd like to share with the rest of the group? That's OK. Again, not all of us get up there and want to talk about our stuff. So when I talked about the agenda, I told you that we talk about article styles, because not everything has to be a how to. You can write different sorts of articles. So the first one is our introductions to and getting started. These are sort of how tos. It's a style to use when you're talking about a topic you're very confident about. If you're writing about that topic, you're introducing it and you're owning it. So look at your list and think about two topics that at some point you didn't know much about, but now you have expertise in. And that could be a good introduction to or getting started guide. I think I have a little bit of redundancy here. I don't usually give the section Marjorie does. So this is introductions to and getting started guides. And then she has a section on how tos and tutorials. So how tos and tutorials list instructional points. They're very bulleted, not a whole lot of rainbows and glitter and fluff. And these are your guides with pictures and diagrams and source code if you're technical or other visuals. So look at your list and see if there's two topics that you're confident that you could write or lead a how to article. For publication, sometimes we do lists, listicles or roundups. These are pretty straightforward. They're lists, they're quick, easy reads where you share information about skimmable tricks, resources, it could be just a roundup of articles with a one line introduction. They have a bad reputation for being clickbaity and cheap for folks, for lack of a better words, but they're great to express if it's not clickbait. It's great to express a few insights in a very digestible way, especially for people who might be on public transit and they're on their phone. Listicles are real great and it takes them to other topics, think about that. Are there two on your list where you have like your favorite tips or tricks that you could do a listicle article? We have personal stories. These can be your career journey. They can be how to set up your Linux desktop or as simple as what you do and why you love to do it. Are there two on your list that you can kind of create a personal story? And that moves into personal stories or kind of case studies, but on yourself. If you're familiar with case studies, their details of case studies are details of a specific subject, situation, person, or occurrence. Are there two topics on your list that you could write about a specific topic, person, event, organization? This can be a case study. And it's funny about how much of the stuff was in the marketing part of the Dries Note yesterday. Remember he said write a case study. So again, there are those details, things of the, how did you set up Drupal for Chicago Parks District case study? And my friend Marjorie, who gives this presentation, loves roundup articles. So roundups are usually reader favorites because they're like those listicles because they're easily skimmable and a place to get all the information and resources. But you do have an introduction paragraph that breaks down that article that you love. So you've got a little bit more information in context with the listicles. So are there two topics in your list that feature several products or resources in the same categories? Or do they have a same theme that you could write a roundup article? And sometimes a roundup article is like, say you have a favorite periodical and you're into Git. So over the year, you found five Git articles that you really like and you wanna share that, you kinda break it down and write a roundup of those five very interesting Git articles. Now we're gonna talk a little bit about documentation pages because we know that they're a little bit different than our articles. So we'll talk a little bit about documentation styles. Again, this is sort of a split and half conversation about articles and then documentation. We have readmes. If you're familiar with the Drupal code base, most projects have readmes. A lot do not have complete readmes, but a readme is a text file that describes and launches a project. It's a text file written in markdown but we can go into that later. But it's basically human readable. It's how to configure what dependencies you need, who you can reach out to if you need help. If you're evaluating a module, we really want the readme to give you enough information to understand if that makes sense for you to extend your Drupal core with the contributed modules. So think about it when you create your own project, but again, a lot of readmes are incomplete and a lot of the code bases. So maybe you wanna get used to doing some technical writing and you have your favorite module and you notice the readme is lacking. You can look up the readme template and kinda redo that and that might be a good first contribution because a lot of the information is there. You don't have to do that blank page, but fill in those gaps. We have user manuals. A user manual is a document provided to a user that helps using a particular system or product or service. It's known as an instruction manual or a user guide. Sometimes in the open source community, they're called man pages short for manual. And these documents cover detailed information about operations, standards and guidelines. They provide some troubleshooting. They might have some advanced functionality and more. So look at your list and see if maybe you could write a user manual. Maybe you've developed a product. You know, we've had our hot water heater delivered and it's a very, there's a lot more information in that than something like a readme. We have reference materials. There's various sources that provide background information and quick facts. While there's all sorts of different types of resources, you've got things like atlases. You have almanacs, bibliographies, biographical resources, dictionaries and psychopedias, handbooks, indexes, statistics, citation guides. These are all kind of clumped into that reference materials. A training manual is a set of instructions that tells users how to complete a job, process or task. We have a lot of these in the Drupal world and we could always use more. So a training manual. They're a little bit more in depth. Again, you know, this is, you know, not just the introduction, but this is different use cases for your particular technology. They're more of a complete instructions to complete a task. And it might have several use cases versus just the intended use case. You know, because we know that when we write a module, what we intend isn't always what the other person intends when they use the module. So it's more complete. So now we're gonna move into getting started. But before we do that, I did say I'd say when the top of the hour was, if you wanted to move to a different session, because this is a double session, feel free if there was a conflict to move to a different session. I will. It's okay if you do that. Okay, so now we're gonna find our why, our what and our words. So this is a writer's workshop, but it can also apply to writing a pitch for a conference like DrupalCon or sharing your elevator pitch. Like people are always asking me, oh, you work for the Linux Foundation. What do you do? Well, you kind of have to practice that kind of stuff. No matter what you're trying to accomplish, there's a few things that you have to think about. Did all those go up? Yeah. What are you talking about? Who are you telling this to? And who is your intended audience? Because those might be two different things. Under what circumstances, they'd use this what, the when and the where, but this could also be where you include the how. So these are those five W's and the H. I don't know if in Europe you have this, but in grade school in the United States, we learned about the who, the what, the why, the when and the where, and then just this weird H, how. So, and it's still called a W, even though it doesn't start with a W. So the following slides, I'm gonna read a prompt and we'll call out the five W's and the H in this reading prompt. And as we go through it, this is your chance to take some of those prompts you wrote down and think about those five W's and the weird H. Okay, so the what, what are we sharing and can you identify the what in the following text? So I'm gonna read a blurb and I'm gonna read it a few times and we're gonna look at the who, the what, the why, the when, the where, and the how in the same blurb going through. So we're, we are a technical community advocates and we enjoy using Markdown to help expedite the editorial process for our community of writers. Markdown helps lower certain barriers to entry by masking the complexity of technical writing and bridges the gap between technical writers and developers. It's straightforward and anyone can get started today. So what are we focusing on here? Markdown, okay. So yes, we're focusing on Markdown in that statement. So the who, who are we talking to? I'm gonna read the text again. We're technical community advocates and we enjoy using Markdown to help expedite the editorial process for our community writers. Markdown helps lower certain barriers to entry by masking the complexity of technical writing and bridges the gap between technical writers and developers. It's straightforward and anyone can get started today. So this is kind of a trick question. Who's the who here? There could be, yeah, there's a few of them in here. It depends on what context you're using, right? So think about that, you know, it could be the we, me and Marjorie, we are looking for someone, but it could be the community of developers. So think about that when you're writing, who's that who, who are you writing to? Marjorie picked writers. So the next one is the why, you know, why do we suggest using Markdown to writers? And I'm not gonna read the prompt again because we've read it, but so in this prompt, why would a writer use Markdown? And also let's see what Marjorie says by masking the complexity of the technical writing. And then the where and the when. So when and where would we use Markdown or suggest using it to writers? And this can be just another way to explain the how in your subject. So when would you use Markdown? I would say you use it to help expedite the editorial process. Let's see what Marjorie says. Yep, to help expedite the editorial process. And I'm gonna give a little bit of context here for people that don't know what Markdown is. Markdown is a language that's human-readable and you put it into an editor and it shoots out HTML. So as an editor or someone who reads maybe it's a marketer, I can read a Markdown file. It's got a couple of hashtags and a couple of bullet points and stuff like that, but I can tell what's written whereas someone submitted that same thing in HTML, I'd be at a loss. Also as an editor, getting an article in a Google doc, you copy and paste and you've got all those spans and all that crud. So when you copy and paste it, you either have all those spans and all that crud or you strip it and now you don't have where they want their links, where they want their headings. And so Markdown is a really a good tool for everyone. People can read it and it's easy to paste into WYSIWYGZ and we have a little bit of Markdown support and core now with CK Editor 5 and then we also have some great new modules that help Markdown in Drupal 10. So it's coming back and being relevant. And then the how, how does Markdown work? It bridges that gap between technical writers and developers. So again, one statement, you know that this is probably our introductory paragraph. I have that who, the what, the how, the why, all in there. So when someone starts reading your article, they know right away if this is the article that they want. So no matter where you are in your journey, understanding what you're trying to say is that first step and you can just keep building from there. At the end of the day, if your audience understands what you're writing or what you're speaking about, then you're on the right track. So we're gonna take some of our topics and narrow them down a little bit, figuring out what you're trying to write. Technical writers are experts at translating highly technical subjects into more digestible formats for the end users. So it takes time, it takes learning and skill building to become a technical writer, but you don't have to be a professional technical writer to write technically and publish your knowledge. So in this section, we're gonna really define what technical articles are and how they're different from documentation. And then we'll do the vice versa on the other, on the flip side of it. So technical articles are an informal way to share your technical expertise. It can be about logistics, it can be practice, it can be the science behind a topic or something that requires a fundamental understanding to grasp or undertake. So they're really informal ways of sharing information. And generally when we look at technical articles, there's three tips we share with our new authors. We start by writing down three things that it requires to do the thing. Start with threes, groups of threes. If there's more than three steps, cool. You can widen the steps and expand your points into another article. It's under these steps that you would write sub steps explaining the main step. So think in the terms of threes. If we think about our school outlines or the way we structure headings, you have your three main topics and if you have something to say about those, do three more. If you have much more than that, maybe it's not an article anymore. Maybe it's a reference guide or maybe it's a series of articles. But our attention spans are short. People don't have a lot of time. So the concept of three works really well with the way people read articles these days. You wanna write a paragraph that introduces why someone is reading your article. Remember that blurb we had? It had all of the things to make sure that people understood and they're not wasting their time. And you wanna closing section to close out the conversation and to leave the reader with a call to action. So as you do it, you have your introductory article, you've got your three points and then at the end of those three points, you kinda digest that again, tell it about it again, and then give them a call to action. Oh, if you wanna learn more, go here. Here's what I did next. Or maybe it's a series of articles. Ooh, this is one. This is pretty hard to read, isn't it? Okay, so this was an article on opensource.com and Marjorie broke it down into the three sections. Here's what it looks like. All written out. You can tell he's got an article, the title, it shortens the sync. He's got an opening paragraph. He's got an image because images are great for ROI, for articles. And then he breaks down a little bit more and then he's got his three points. So his three points are society and culture, rough resources, infrastructure and economy and proprietary software needs. So he breaks it down into digestible chunks for people. So now let's look and flip it over and look at how we write technical documentation and how it's a little bit more formal than an article. According to Indeed, technical documentation is a more formal style that describes the application, purpose, creation or architecture of a product or service. So with technical documentation, we wanna think of economy of words. We wanna eliminate words. We want to be clear, concise and succinct. We wanna be careful of jargon and buzzwords and pop culture because we live in a global society and people all over are using our software. So localisms don't always translate from translation to translation. More specifically, we wanna eliminate words that don't directly enhance or support the purpose of our documentation design. We wanna use specific nouns. We don't wanna use words like thing. That should be eliminated from your lexicon. You should search for thing and just delete that. A lack of noun specificity can cause confusion because what things, what people, the sentence lacks meaning because of vague nouns which will force the reader to add extra sentences themselves to clarify the purpose of what you're saying. You wanna really make sure that you strengthen verb phrases. You wanna use an active voice versus a passive voice and I am awful at this. I really have to look and make sure that I have written in an active voice because verbs are the heart of what your sentences are. When they get watered down, they become weak and again lead to that user confusion. Active voice means that the subject of the sentence is doing the action and passive voice means that the subject is being acted on and I'll say that again. Active voice means that the subject is doing the action and a passive voice means that the subject is being acted upon. And when we talk about technical writing, when we write in the passive voice, it goes against the rule of economy of words too. It takes a lot more words to write passively and again it adds to the confusion. We wanna avoid walls of text. We wanna break down our content with bullet points and numbered lists. Each point should be brief and easy to understand. They help to prioritize the information that your content consumers are using and break down those walls of text. Walls of text can be very indigestible and that again, when we're on our phone and a wall of text takes two scrolls, you're gonna lose your reader. So break it up, use headings. Organize the content logically. That's the headings and the subheadings. And this is good for accessibility too. When we use headings, we structure our content in a way that assistive technology can follow it. So headings aren't just for styling, headings are for breaking up your content and again, headings are for assistive technology. If your team has a style guide or you know, Drupal has a style guide, Drupal has a template that we use, use it, you know, be very clear because you know, we're going to, you know, like I work at the Linux Foundation so I'm just gonna use them. People go to the Linux Foundation and they're reading technical documentation and the way it's written changes from page to page, it can be confusing and inaccessible. So if you have a style guide for your project, a style guide for your blog, you know, keep to it or keep the best. You wanna familiarize yourself and reference it when you have questions. It provides rules and guidelines for consistent writing and sometimes what people will have is the have an accessibility guide in there too. So you might not be 100% versed in accessibility but your style guide will give you some clues to keep your content accessible. So for formatting, you know, we talked about this, we have the headings and then we have the subheadings. If your article is longer than 500 words, consider breaking up that text so you don't have a wall of text. You know, we use our H2s and our H3s and our H4s. Typically that H1 is the title of your page so we stay away from that. There's some rule or there's one browser where you can use an H1 but generally speaking we start with an H2. If your article is longer than 1300 words you might consider breaking it up into two articles, you know, or making a longer series. When we write interviews, we wanna make sure that we use bold for the questions or bold for who's making the statement and the regular formatting for the answers. So you wanna have a visual clue and then a semantic clue for a screen reader that it's the question versus the answer. And then inline formatting, you know, some publications will allow you italics and bolding but use those sparingly because maybe in the WYSIWYG they're not marked semantically so if you're using a screen reader maybe they won't know that it's bolded. So if you use bold be aware that sometimes only people can see that visually. Code formatting, if your article contains code please delineate it with a code tag. You know, there's two different ways that you can do it. You can do inline code or you can have a code block. If it's a short piece of code, you know, feel free to leave it inline within the snippet, you know but those longer chunks should be broken into new lines. We don't recommend using block quotes for code blocks. Also, do not take images of code blocks because you're sharing information in the code block and now your content consumer has lost the ability to copy and paste it. So if you do use an image of a code block for whatever reason, you're gonna have to write it all out in your alt text anyway. So but again, you know, it gives your consumer that ability to copy and paste. When you're writing for a publication you wanna be careful about underlining for formatting because most people associate underlining with texts or with links and if your links aren't underlined please consider underlining your links but most of the time for formatting it is for links and people will recognize it as links and they'll go to it and it's not a link so they get confused. So we wanna avoid using that for formatting. When we talk about hyperlinks within the article we wanna make sure that, well, it really depends on your style guide but for accessibility you wanna make sure that the person knows that they're either staying in the page opening it in the same window or if it's opening a different window you wanna indicate that you're opening it someplace else because it might be disturbing or frustrating for people that don't know what happens when that link opens. So make sure that you tell folks with a little tap with a description if it's gonna be opening in a new tab or it's gonna be opening in the same page and then keep it consistent from page to page. Going back to who your content consumer is creating a persona is sometimes a good idea if you're thinking about who you're writing for you should ask yourself the reader you're looking for who's gonna read your document what information would they expect to find. And then evergreen content when we talk about things like readme's and the technical documentation evergreen content is really important we don't wanna reference things that have happened in the past or that are gonna happen in the future because then it's not relevant anymore. So if you think about that if you don't have content that's evergreen you need to keep going back and updating it. So revise and update because we know that tech changes so build that into like your development plan of when you're writing things build in that time to go back and improve your documentation as you add a feature request as configuration changes because core changed go back there and update keep your content as fresh as you can. So there's a talk right was there a talk yesterday about AI or I don't remember but it's happening now okay so some of you know me some of most of you don't but I'm very opinionated I'm very open source so I do wanna talk about the use of AI a blank page can be a really scary thing and that's okay and it's okay that you use AI the AI I'm talking about is beyond using something like Grammarly or spell checkers what I'm talking about here are writing assistance like chat GPT I think that's the big one so I just wanna say a couple of things to keep in mind when you're using these AI tools one are they attached to an API and are you sharing your information so think about when you're using an AI tool and you don't want your information to be on the internet is it attached to an API first and foremost and then AI models are only as good as the data they have access to so hey how much information is totally correct on the internet you know so the governance is always changing it's different in Europe than it is in the United States when you use AI all of a sudden it might not be open source anymore so where they're pulling from might be proprietary information like code from a Mazda database and you use it in your home assistance well you're gonna get in trouble because you just pulled some proprietary code it might not be accurate so really if you use those AI tools do your fact checking go back and make sure that those resources match and use the content but be sure that you make it your own through edits so that's all I'll say about AI you can think about all the other stuff but as writing keep in mind we're working on open source projects and it might not be open source and it's biased too AI is inherently biased because it only has what it has off the internet and we all know the internet has biases okay so spelling and grammar most of the time if you're writing for a publication you're gonna have some editors that will help you with it so maybe English isn't your first language and you're a little bit nervous about putting in your article or I'm being very American here by saying English but maybe you know you're writing for a different language than your first language you know it's nice that you go through and you do a copy edit but know that that editorial team is really rooting for you and they'll help you with some of that stuff so don't get hung up if you're writing for a language that's your second language the process is expedited if you've done like some of that basic stuff but I wouldn't let that be a hang up word count you know I talk about word count a little bit I told you about the 1300 words and stuff like that and that's a question we get asked a lot about articles most of the time we don't worry about word count so neither should you you know but I put together some guidelines just in case people want some guidelines on word count oh my gosh okay that is not accessible is it sorry about that it looks much different on my computer but I will change that for the next time I give it and what I mean by accessible is it's really hard to read that color on that blue okay so when we have 500 to 600 words 500 words might be all that you need to provide a project update announce a conference or share some sort of timely news story 600 and 800 words this might be for reference a in print a one to two page article with pictures so that's what you know in print a magazine 600 to 800 words would look like and this is good for your regular article or a column submission an interview or a roundup consider you know adding those subheads to break up the text and walk your readers through the section of the article and then when we move into 800 to 1300 words these are our how to's these are getting started guides these are our tutorials you know more in-depth roundups things like that and then 1300 words sometimes it's really hard to get all of your information out in less than 1300 words so don't let that stop you you know just think about you know how much more how many more words do you have you know does it go beyond 1500 words does it go beyond 1600 words that's when you might consider breaking it up into two articles or if it's a documentation page making sure that you have maybe break it up into configuration and then another page on troubleshooting you know break it up because people want those digestible chunks and it's easier to come into one article than to come into two articles than to go into one article multiple times to find what you're looking for I hope that made sense okay images so we use images both in technical publications and in documentation because sometimes they enhance what we're learning sometimes people don't learn by the written word and those visuals help them you know digest the information inline images and screenshots they add visual interest too it breaks up the content you have a picture to look at if you have a hero image and it's on Google people are more likely to click on it with that hero image they're more return on your investment if you include images make sure that they match the license that you're using that you have permission to use those images and then if you provide your own images make sure you declare what kind of licensing you have on you know is it creative commons can people share it most of the time if we're writing for open source we just open source everything but make sure that you can share that image and give attribution so I just said this include image credits and license details when you submit your drafts to folks that way they can look up and make sure that that image belongs to you or they have permission to use it when you submit your images submit them as files or attachments they should never be inside your draft maybe make reference in your draft to where you want the images placed but it's easier for editors to have those outside of the draft it's easier when you submit your read me or your technical documentation to Drupal.org it's easier for the person entering that content to have them separate it's hard to extract images sometimes from things your images should be no wider than a site's columns width and usually that's about 600 pixels there's tools out there GIMP you can put in an image and you can use GIMP with a few clicks you can reduce that image size to fit and then when you do manipulate that image make sure that it looks good after manipulation we don't we don't want it to be pixelated or blurred or too big because think about loading I might be in Mexico and I'm reading an article and if you have a real what's the word I'm looking for large image it might not load in time and it's the same as not having an image at all use labels when you submit your images so your editors know where to put them add captions if they're applicable be sure to reference in your article where the caption should go you know if you do this put the caption at the bottom provide alternative text now it might just be a picture of a big red barn right so what would you put big red barn but depending on the context of your article that big red barn might just be a big red barn but it might be a big red barn sitting in a field with bombs exploding around it so not all alt text is the same so think about that and what you think the alt text should be might read differently than what I see so if you have some sort of emotion or you want to get something out in that image you're provoking you're providing more context that editor might not know that so provide as much of that as you can oh Martry put this in here I can talk for hours and hours about captions and alt text um yeah anyway thanks Martry decorative images are weird okay why is it in there if it's a decorative image are you evoking emotion if you're evoking emotion why would you not describe it to a person who can't see it I'll leave it at that so links usually links are approved by the by the periodical you're submitting to if the primary purpose of your article is all about backlinks to your organization is that really great content to share think about that do they folk who are you submitting to do they focus on stories about open source products technologies communities or products you know although a product pitch is okay it's not a good fit for every site maybe you have a product pitch and it's a great thing maybe just use one link back to how they can get to you at the bottom but the whole links inside people feel it's not a good feeling for people when it's a product pitch that's you know all about getting them back to your website save that stuff for medium or linked in so include links to open source products or Wikipedia pages you know describing the project when you're first mentioning it maybe it's you know you're using D dev well the article is not about D dev but you need to add some context you know link back right there at the first link at once so they have the context and leave it at that explain the link to other open source licensing so you know if you're writing an article about Drupal but MongoDB you know they have two different licensing so link back to licensing and things like that and then include links to technical ideas and terms that may not be known to a non-technical audience because not everyone is going to be technical reading your article so if there's a big concept in there do people because you don't want to explain the concept in your article because that's not what the article's about but you want to be able to provide context for people that don't know about that specific thing so again you know link appropriately so now what when creating an article there's certain key things that we think about you know the first thing is a title you don't have to start with a title but sometimes that's how people work so um after that you want to create an outline and the outline has an introduction it has a body we talk about you know key elements and then when you wrap up your article and call the actions so titles usually we talk about this first you don't have to do it first you know sometimes the inspiration for a title comes later um you want a good title for your article you want it to be catchy playful yet explanatory but we need to be careful of too clever of titles right um what you might think of as quippy might not go over you know might not translate well you know like I said certain pop culture references are great for one localization but don't carry over um and try to create a title that can stand out on its own so you don't get too caught up with the headlines and then think of search engine optimization um when we're doing contributions and we're doing our issue summaries and our issue titles we keep them clear tight and concise that way when other people have that issue they can search the issue queue same idea with an article if we're going to keep those words clean and concise and what you think people would use to search for whatever topic so an example we use sometimes does she have that in here no um like we had a a session submission one year for florida camp that was like php self-defense and some of the people were like well what does that mean you know so like some of us know what that means but others don't so you know it's a neat title if you know but some people would just skip over it so just be aware of those two clever of titles and then we want to keep politics out of the titles too you know anything like that so the outline you know um be clear about what it's about what are you going to cover in the introduction why does it matter we want to peak the interest you know again we want to make sure that those people reading that first paragraph really know what they're getting into um give them an escape route by giving them as much information as you can and who's it aimed at those W's in that H and the body you know we break it down into those threes so we have the main topics like story headings you know maybe the main point of what you want to have have that be first think about that you know like don't be flowery and that sort of thing just go in and tell people what you want um what are some examples or supporting points to illustrate your main point and then logical flow changes as you write your article too so give yourself some grace as you're writing your articles like oh none of this makes sense it's in the wrong order sometimes all it does is like finishing the article to have that aha moment of putting it back into order you might have to change a heading or something like that but don't get hung up on keeping exactly to your outline so if we write an article about a module and again this is just an example you know looking at those points you know who is that project for we're writing about a module what does the project solve why was the project created what solution are you providing how does it work when would you use it and where would you use it so that's just applying that to like a you know you wrote a theme or you wrote a module but you know those are the questions most of your content consumers are going to be looking for for a conclusion um we had that introduction paragraph right we talked about all of the things we wanted to talk about that conclusion might be two paragraphs but you're going to remind your consumer of what you wrote about you're going to remind them of the details it won't look quite the same as the introduction but you're going to leave them with some key points to remember because sometimes at the end after you've digested information being reminded of what you just learned and that one of those sentences like did I learn that and it gives a person an opportunity to go back and make sure that they learned all of their things but really you want to answer that so what question why does it matter why did they just read your article the so what factor and this might be a place to um have your bio and we talked about like links to agencies or links back to your organizations or links to things a bio is a place where you can link back you know you know I'm Amy June and I work for the Linux foundation my link and so sometimes you can use those bios to give people your contact information or a little bit more context you know so if there's something that if there's something that sort of says why you're qualified to write that bio like who am I to talk about accessibility and you might want to list some reasons you know who am I to talk about the media module so your bio might change from article to article 2 accessibility tips um you never want to assume that everyone will consume a resource in the same way so think about that not all of us read articles some of us use text readers some of us use a keyboard to access the information um so not all of us know all the acronyms so define acronyms, numerums, and abbreviations so the first time you use something like BLM you should spell out Bureau of Land Management or Black Lives Matter and then put it in the quotes because there's two different acronyms there Bureau of Land Management depending if you're over 80 years old or Black Lives Matter you know so define define your acronym before you use it a numerum is something like accessibility or internationalization I18N 18 letters in between but not everyone knows that so define internationalization I18N and then use I18N and the rest of your um article use predefined reading levels um the usability.gov and I think there's one in the UK too um suggests writing at the ninth grade reading level now you might have specific audiences or white papers where reading level might go up but we suggest that you write at the ninth grade reading level because there's more people at the ninth grade reading level than at the collegiate reading level and that goes back to like breaking down your words making sure it's understand again there's exceptions because you have white papers or medical paper but you know also as a group like if it's an article that you run with a company or you ask them what their predefined reading level is you want to use clear fonts and avoid special characters so not everyone knows what the ampersand is so just use the and you know I know some of us will use economy like when we're doing our social media posts and stuff but in an article or documentation we want to really cut down those special characters because they don't always translate globally um avoid emoticons and ASCII art um because if you use a screen reader a screen reader will read every single one of those things in line like they're really cute to look at but you have a like a I'm just going to use Twitter because I hate it or whatever it's called now you've got a post and it's talking about like a graduation but every other in between each word is like an emoji that screen reader is going to read that one word the emoji the one word the emoji the one read so if you do that in an article you're going to lose your content consumers really fast and then ASCII art they're going to read all of those slashes all of those factics all of those so in a read me like it was really cool and you have this great cat it's really going to frustrate some of your your people using assistive technology so some parting tips that Marjorie leaves us um we write to one person so we use a singular um it's not we it's not let's it's you or the user we write as if the reader is doing the task right now so no will no should no could you're writing it as if they're doing the task right now and then you write for one clear result you're teaching you're persuading you're enlightening your reader about one idea bonus tips don't really count towards that idea of three so if you have like this kind of tangential thing that's like oh I really want to share that you can kind of you know there's you know exceptions to every rule and then try typing your topic into a search engine to see what people are saying about it what are people what are people searching for you know what like you know you look at your article and you think oh this might be incomplete type in those search words and see what people are searching for and then use markdown and I have a little bit of an introduction to markdown we've got a few minutes left does anyone have any questions before I kind of like do a little bit of a markdown demo that's okay okay okay well um before we move into the demo I want to uh well in light of a prominent community sponsor here at Drupalcon I want to remind people to be sure to read your host accessible uh acceptable use policy and make sure it aligns with your values and goals and that's all I have to say about that if you want to ask me more you can ask me after the recordings off because they are sponsoring this camp okay so why markdown um markdown's cool pdfs are a dredge pdfs why do we even have pdfs like why do they exist in this day and age they're portable documents but they're not accessible you can't copy and paste from them they're the most they're just pieces of junk right do not submit things in pdfs google doc is better than a pdf okay that's how bad pdfs are um so one of the things about markdown is um it's really plain text formatting but it allows it's a cross between plain text formatting and html so it kind of bridges the gap it allows you to have more control over your editorial view of what your article looks like you can add headings you can add links you can add borders you can add flow charts ooh so and they're very human readable you know like I said you can submit an article to maybe someone who's not technical on your marketing team or maybe your intern who can't read html but it can be converted to html it's portable from different technology to different technology as well ascii doc is cool too and drupal.org references using ascii doc but I've never seen anything on drupal.org written in ascii doc has anybody no okay because it's still up there that says submit your stuff in ascii doc okay you know okay so why use markdown it's because it's cool um it's intuitive it's portable it can be converted to html it can also be converted to a pdf um but using markdown is like using an editor without having to use the buttons you know like when I'm typing real fast like my finger does not reach some of those buttons so um to like up at the top of the whizzy wigs say I'm like down so I have to like almost like put my I have to like take my fingers off the keyboard go to the mouse go to the button you know where markdown's just keystrokes so it's accessible to people who maybe don't use a mouse maybe it's accessible for people who's you know have a palsy or something like that I already said this earlier but um it's now in core so that's kind of cool so it's still relevant Mike Inelow just wrote a markdown module called easy markdown I don't know I know that I didn't um move some of my sites over because markdown wasn't available because Mark Conrad did an excellent job with the markdown module but it never got ported to Drupal 8 and Drupal 9 and Drupal 10 it was a very big he's a very gracious fellow and took every feature request and it just was really really big so Mike Inelow did a a very straightforward markdown module just recently and it's called easy markdown so I've been using that and it's great it works everywhere it's good for almost every editor across platforms you can use it in linux you can use it on max you can use it on windows um and I already said all this stuff so just skip it so applying the basics to markdown so you start with an md file so most of us you know when we do text documents do the txt file but if we write markdown in a txt file it won't render so we're going to let our editor know that it's a markdown file so you start with that md file you also have to sort of pick a flavor of markdown if you're not familiar with it different places have different flavors they're like dialects we have get hub markdown we have get lab markdown we have common markdown so kind of pick your markdown flavor and then make sure that you have an editor that helps you render it so do some a little bit of homework on that um vscodium is a great open source um editor because vscode is not open source so y'all know so vscodium doesn't track you but it has the ability that you can write your markdown on one side and it renders you can pop out a window so you can see what it's going to render so that's kind of cool to find a good editor um here's some open source editors you know I mentioned vscodium um because that's an IDE that a lot of folks use um vscode uh joplin's another great one adam's okay it's more bare bones not so cool editors these are the ones that aren't open source um but they work good obsidian is a really cool editor but it's not open source and they use your information so I can't recommend it so it's on the not cool list but if it does like mind map kind of stuff playing around with it is cool I've been asking for years for someone to write an open source version of obsidian um but it's not open source but like I said it's worth mentioning because it is it is kind of cool or not so cool so these are some of the things I think that we're going to talk about let's see where we're at eight minutes do you want to look at a github repository and look at like how kind of straightforward markdown is okay so I have to change just a little bit I have to so I have a github repository Amy June Heinlein and it's marked down in minutes and I've got some files and I'm just going to kind of open some of these the best I can being on a different screen footnotes is in progress so we're not going to look at footnotes oh shoot well that's opening a new window so we'll look at headings first so this is gitlab as you can see it's rendered but if you want to look at the code just come over here and look at the code so there's a couple of different ways you can write headings you know we if we look again and we switch over we had that real nice styling right but it's pretty straightforward it's a hashtag with a space and a heading so hashtag in a space and as we work down our headings you add hashtags so our heading one is one hashtag our heading two is two hashtags and so forth and then alternatively there's a way that you can write an h1 and an h2 and we do this in most of our readme readme's in Drupal as we use this style where we have heading one with equal signs and heading two with dashes so if we go back and we look at it we've got our heading one heading two, heading three, heading four heading five and all we had to do was add a hashtag as we went and then gitlab styles it with a horizontal rule I don't know why they do that but um horizontal rules are basically three dashes so if you look at it three dashes is our close this one and look at some of the other ones code blocks we talked about two different kinds of code blocks we talked about inline formatting and we talked about code blocks it's real hard to see but inline code you've got a little shadow can you see that it's got a little bit of a highlight behind it and then you we have code blocks and these are style different ways depending on where you are but it's got it in a block and sometimes you'll see it in the in the highlighted two but if we just look at the how we wrote it our inline code is one tick what we want inside of it followed by or back tick and then to do a code block you've got three back ticks on one line followed by what you want in the code block and then finished with three back ticks so we'll look at that real quick so and again we do code blocks because they're easily copy and pasteable what else did I have up here I'm just kind of showing the cool ones that not everyone knows about oh we broke this in Minneapolis but here's a flow diagram like I don't have to pull out my figment editor I don't have to do a bunch of stuff I don't know how to do again we broke it and I haven't changed my demo since then but if you look at the code part you announce a library oh we broke a table before so the stuff on the top is a table that we broke but the stuff that starts with mermaid here is our flow chart so we're telling it to graph it we're saying going from A to D B to D D to C so if we look back you can see A to D B to D D to C so pretty straightforward it's accessible you know your alternative text is included when you do this so you don't have to think about it but we had a cool table oh I forgot about that this one person in this last time I gave the demo wanted to break everything like what happens if you put a table and a flow chart and then you do this so what's another good one lists are good I'll do lists and I'll do tables just because just because like I said most people don't know that you can do and maybe we won't necessarily go over exactly how to do it but you can see that it can be done because I've got two minutes okay so we did flow charts we look at lists lists can be done in a couple different ways to create an ordered lists you do one two three and four or you can just do whatever numbers you want because when you flip over mark down we'll put them in order for you so see what it did we had one one one one and then it flips over two one two three four so that's an ordered list unordered lists you can do in a couple of different ways you can use dashes asterisks or plus signs so here's they all look the same here but if we look at the code we have dashes asterisks or plus signs maybe the plus sign is easier for you to use so that's why you use pluses over asterisks there's no reason why you do one over the other except for preference and then the last one down here is combining the two so I have some ordered lists here and then I have some bullets inside so if we look at the rendered you can see that you can combine the two so we have an ordered list with some bullets in between again just using those pluses minuses and asterisks and then the last one is a table hopefully it's not broken great it's not broken look at this you can do a table and mark down cool it's accessible and pretty straight forward so I have pipes you know it's that key on the left right hand side of the keyboards pipe symbol I have a table and then I define my tables we're going to look at a little bit so if we flip over we can see the columns that are left the columns that are right and the columns that are centered so pretty straight forward it's just where you put that colon determines where that table's going to be tables do not have to have information in them but then they're no longer accessible because a screen reader doesn't know what to do with that spot but it's an option for you and then you can like change it up to you don't have to have everything on the left or the right hand side so if we flip over and look at that code you can see we spiced it up you know we have you know one column is on the left one columns in the middle and one columns on the right so that might be something for styling you know that helps people read one thing to mention about when you center align things if the text is really long in a table it makes it centered and that's not always easy for people to read because it doesn't have a clear one side so if it's just one word you can center it or a couple words but if you have a big block of text for accessibility keep it to the to whatever side of the page that that is your language is written in and then one last one that's just cool look at this this is a task list where you can like check off things and of course I do something where I like show y'all how to do you strike-throughs and stuff like that if I had time but if we look at the code it's just kind of a combination of everything we have a completed task to do strike-through and mark down it's a tilde on both sides of the word and so we filled in our test list with tilde and it crossed it out so it's just that you know the power of it is spectacular there's a lot of things that you can do without even having to use your wizzy-wig buttons this one's kind of cool too you can do a drop-down look at that and mark down and I'll just show you the code so we have details in a summary you know our answers and then you know a drop-down and there's other things that you can do drop-downs you can like make it a radio button and things like that and mark down but these are just like the power of mark down like I said you don't have to have an editor you just have a mark down file and you render it and it's a great way to kind of um human readable that's the important part too right you know and it converts it to html so you have your styling and you have control over it and it formats it in html which renders it on your browser so three minutes over sorry folks so but thank you and and the mark down repository like feel free to play around it's like Amy Amy June Heinlein if you find like my repository it's marked down in minutes and there's a whole bunch of different pages that you can look at and flip between you know how to strike down things how to how to make things bold how to make things you know italicized so yep okay thank you