 So I'll do a little bit of housekeeping while Marjorie's passing stuff around There are some images in this slide deck, but most of them are decorative or the context is already going to be said or on the Yeah, been verbally said so we won't be describing any images unless we have to Because this is actually a three-hour workshop that we submitted and then they told us we had a 50-minute slot So there's a bonus section at the end if we have time on like how to write a little bit of markdown But we have our link to the slides there if people want to follow along there's some there's some resources to good markdown editors and then Also, you'll be able to see that section on markdown and we'll add to it tomorrow If we run out of time you can do those bonus slides at home and that's a bitly link bit.ly Drupal con hyphen writer hyphen workshop and I'm Amy June Aaron when born award winner 2021 But I'm going to describe my image because I'm wearing a Drupal camp Asheville shirt and Drupal camp Asheville is July 7th through 9th in beautiful Asheville, North Carolina And one of the things that me and Marjorie did in a past lifetime was we were Editorial managers for some very popular open source and architectural magazines online They no longer exist, but Drupal camp Asheville has a Neurodiversity initiative where we understand that not everyone likes to present their content verbally through presentation So we're accepting articles So if you an article comes out of this you free feel free to submit it to Drupal camp Asheville And that's Marjorie Freeman She has not won the Aaron Wynne Warren award yet yet Thanks for having us everyone So I Made this presentation We made this presentation a while ago, but I added some notes to it because I met somebody yesterday who asked me Why we were having a writer's workshop and usually I have You know, I have this elevator pitch of why we do this and we worked at red hat It was because we want to encourage people to write and write various sites And he was like well, how do you encourage people to write when there are things like chat GBT and other natural language processing tools like what makes somebody writing You know for themselves different than just using a tool and I was like There there's a certain human touch that comes with being able to write about your expertise versus using a tool for it and As a community advocate, there's nothing more gratifying than helping someone write their first article. So that is why we give these workshops and We hope you can leave with something helpful And oh, so why this workshop, you know We're here to help you find your why you're what and your words Because sometimes because we have this workshop sort of broken in two parts One's about technical articles and the others about documentation and the technical articles But some people struggle with because they just don't know where to start so we're gonna help you look for that How what and why? So why do we write? Well, we want to share our information and our expertise with people We want to share our information. We want to promote our projects. We want to promote open source Perhaps, you know, the job market's kind of weird right now in tech. You need to build a personal brand You know, you publish an article that's something that you can have on your LinkedIn presentation It's something that you can you have on your resume and we all know that when you teach something you learn something You learn by teaching people And then also we want to create more experts So this slide's just up here for the QR code if you want to connect with us on LinkedIn These are at the end too So we're just gonna pass because we already kind of talked about ourselves and there's Marjory's QR code Do you have anything else you want to say about yourself? No, okay? Um, so what are we gonna do we're gonna do a little bit of a brainstorming activity It's gonna be kind of a flash brainstorming activity because it's very Abbreviated workshop so again finding those words the what the why the five W's and the H Remember that weird H the how to kind of pinpoint and look at what you're gonna say so Like I said before we're gonna do technical technical articles and documentation because they're written differently They have the same kind of information Almost exact, but they have a different flow and then if we have time we'll look at the basics of markdown because markdown is a spectacular language That is human readable but can convert your stuff to HTML easier and as editors We really appreciate when your articles are not in a Google doc and in markdown So think of that but then you know markdown is gonna be in the next triple release I heard in the CK editor 5 so that's kind of exciting. So might as well learn it Okay First we want to talk about a little bit about Why we haven't written, you know, perhaps, you know, you're from an excluded community or you don't feel you have the skill set So I'm gonna just kind of breeze through some common myths that way You know that other people might feel this way and then I want to talk about why they're really myths Lots of people won't write because they don't think that they're an expert You don't have to be an expert to write. Everyone has a different idea of what expert means And no one knows everything and everyone has something to learn You could know more about your topic than someone else and then your life Experience on that same topic is going to be different than the life experience of someone else myth to people will Make comments on my articles or in the issue queue and ask questions. I can't answer and I'll look like a fool People might ask you questions and that's okay, you know, but most of our readers understand that not everyone knows everything You have failed if your page views are low if you reach Three readers today. That's three more readers than you reached yesterday And what they take away you might not know that's 300% markup, you know, you've enriched and you've bettered three lives And then we have myth for we get this a lot when we when we solicit articles is how to is the only format Used to share my knowledge. There's all different types of articles that you can do And I don't know if we go through the different types because we don't have time But there are more than just the how to's So the hardest part about writing is actually starting and there are resources to help and we'll show the slide at the end So there are open source comm and enable architect no longer exist Whatever, but we do have other places where we found that are good for submitting our technical articles There's cis admin signal where they talk a lot about the cis admin kind of culture as a contributor you can expect Editorial services technical reviews final approval you can have final approval of your Article before it's published and if you have a topic you want to cover you want to contribute there is a Email address up there and again, you know, we had those the links to the slide And I think we have them at the end too technically rewrite is from one of my writers in the open source to Community that he decided since open source comm no longer exists. He's gonna start a website It's a community of technical writers technical editors copy editors and web content writers And they would love to share everyone's story your article can be anything related about technology such as tools tips How to get started what you've learned in all kinds of other topics and I mentioned Drupal Camp Asheville July 7th through 9th And beautiful Asheville, North Carolina We have the initiative and there's the link there Drupal Asheville comm submit an article and there's a little bit of a process and a form to fill out But we will welcome reviewing your first article and then there's the drop times a new kind of Magazine that we have I don't have too much information. I just know that you can do info at the drop times calm Okay, so Getting started finding your why your what and your words so a Story is comprised of a beginning a middle and an end They don't always start with once upon a time, but they should always leave the reader wanting to stay until the end in This section I'm going to share how to pinpoint what you're trying to say Why you think it's worth sharing and how to make your voice better heard And we hope that the tip is that we share will help you do just that So Amy June is going to go over some prompts and that's why I passed out the notebook and the paint again We're going to breeze through these but they kind of give you a little bit of an idea a little bit of a starting point So when we do the how it's what's and why is you can look and kind of refine your stuff So first we're going to Help you answer the question. I don't know what to talk about. I don't know enough to talk about it We're write an article. I'm not an expert in anything, you know So we're going to do this brainstorming exercises and you can write down as many topics as you want It'll be brief, but you know, just we're not looking for good. We're not even looking for we're not looking for perfect And we're definitely not looking for good. We're just want the big the bad and the ugly You know all the stuff that you got in your mind just brain dump it You can draw you can do mind maps. That's why we passed out the little Card books With while you're summoning your inspiration getting writer's block or anywhere in between We'll be doing these prompts to kind of help you get started and remember It's always good Especially if it's your first article or your first piece of documentation to write about what excites you It's a little bit easier when you have a little bit of passion behind your project so the brainstorm and These are Drupal specific What is your favorite module or theme or version of Drupal because we have till 2025 What cool tricks do you use all the time? So remember the tricks you use someone else might not know about What cool thing have you created? What is the last thing you learned and? How did you learn it? What do you want to learn next? What is the biggest challenge you've ever had with Drupal and How did you overcome that biggest challenge? So think of like case studies We'll add some more of these prompts to the slide deck because we usually like I said It's a longer workshop So we'll put more prompts in the slide deck that Tonight so you can look at it in the future and kind of get a few more ideas those written down We'll go over well first I'll talk about the five W's and the H and then I will go over a sample passage That you can use some of the ideas that you wrote about and kind of walk through identifying your W's and your H so Many of you probably learned about the five W's and an H in elementary school, but I'll just go you know over them really briefly again So your who your your what is what it is you're talking about so the tool Or whatever subject you're trying to tell your specific audience about your who is your audience and Your when and where is tricky because it can also be a how but it's also like what? Circumstances would you use or would somebody use X expand your what? Why should they even be reading about this tool? Why are you writing it? And why do you want people? to know it's so important and Then how can they use it? This is going to make up most of your body text? How are they house is going to benefit them? How do they implement this? What challenges did you experience while you were working with it and how can they overcome it? So I Will Show go through a series of slides that will show The what the who the when the where and the why and then I'll just kind of open it up and see if anybody can identify Each part of the passage It's okay. If nobody speaks, but if you would that would be great. So there's not like that awkward Okay, I guess I'll go to the next slide, but no pressure Okay, so the what is What are you sharing about? And I'll go to the next slide and then I'll ask if anybody can actually identify the what in the passage So I know if I can read but I'll read it anyway We are technical community advocates and we enjoy using markdown to help expedite the editorial process For our communities of writers Markdown helps lower certain barriers to entry by masking the complexity of technical writing and Bridge the gap between technical writers and developers. It is straightforward and anyone can get started today so What are we talking about in this passage? Markdown. Yay That was easy. Thanks for answering. So I didn't have to So who the who is who your article or summary or your idea is targeting So in the following passage just call out who you think the who is I got scared I was like, oh my god to have that highlighted who so who is Markdown intended for and when I was writing this I was like, who exactly are we talking to you? But I'm curious to know if anybody can pinpoint writers and then I had Really small I highlight it technical writers, but in general we're talking about writers So you guess correctly and then why do we suggest using markdown? I said to sorry type of for our writers and can you identify the why in the following text? I Am not using markdown right now But but we'll talk about it later, and I feel like I don't want to doubt Go ahead. Okay. I'm up for debate on this one, but I actually put masking the complexity of technical writing just because That is why I'm recommending Ending markdown for writers, but I think Well, it could be any it could be your point of the why yeah I might be different than mergers in this one. Yeah, and that's I mean, I guess that's another point like why are you writing about? Markdown Imagine you have anything to add to that like Every every article is subjective, right? So everybody's why it's gonna be different So yeah, but that's why I put We recommend Markdown for writers because it helps us in the editorial process and then the where and the when When and where would we use markdown or suggest using it to writers? This can be another way to explain how your subject will be used so When do you think when or where would we use markdown? When are when or where would Amy June and I as technical advocates use markdown? Exactly, yeah, I was confusing myself forgot we're talking about me and you not the actual writers. Yeah so yes the editorial process and Then this is where you define the application of your what? so This will be like the actual meat of what you're trying to talk about This is usually what prompts someone to want to read your article on our editorial team at red hat we had an SEO team that specialized in optimizing articles for search and The how is definitely a section where you'd want to be as descriptive But as concise as possible so people can pinpoint exactly what they came there for so the how might be of the section on Google that comes up in the results of somebody like Search for whatever like that might be the the summary under the the URL So you want to make sure that you have a section in your article that clearly states Or Introduces how this tool is going to benefit the reader so can anybody Pinpoint how we're how markdown would work in this context and again, they're probably multiple answers And I think I heard somebody say it earlier Yeah and I think I think there is much up for debate between the bridging the gap and Lowering the barriers to entry but if you guessed If you guessed this that's that's what I had so that's that's as right as it's gonna get but again it's subjective based on who you are and Who you're intending to reach through your article, but ultimately no matter where you are in your writer's journey or Understanding what you're trying to say is the first step and you can just keep building from there And at the end of the day if your audience understands why you're writing or speaking if you're at conference About a particular topic You're on the right track so and now We'll get into now that you have your Your who what when where and why and you're how written out. This is where you figure out Okay, what exactly am I wanting to write? So when people think of technical writers, they may think of experts who specialize in you know tech of technical documentation and translating highly technical subjects into digestible formats, but Anybody who is an expert on a certain subject can be a technical Writer because they they own that knowledge and if you know how to parse that information and translate it Then you own that subject so In this section, we're going to define what technical articles are and how they're different from documentation Which is something a technical writer or a subject matter expert or practitioner might write because that's what you are so technical articles or blogs are An informal way to share about your technical expertise It doesn't have to be about technology per se, but it can be about the logistics practice or science behind any topic that requires a fundamental understanding or to grasp or undergo so When Amy June and I were working with our different communities We there was a certain process that we would use to help coach mainly new writers who were new to publishing about what they do and Generally, we tell them to start with the three steps it would require to do the thing so write that down And if there are more than three steps, that's fine that could turn into a great follow-up article but You can actually build on these steps and write sub step Sub steps, which would go on to inform the body text of your article But if you can pinpoint the three points that you really want to say you have the rest of your article You just have to flesh it out so Once you have those three steps written out you can Actually form your introduction and your conclusion there sometimes it's tough for me personally to start out with the introduction because it's like That is the point where you want to have people blued in but you can't have people blued in if you don't know what you want to say so write down The three things that you want to say use that to inform that first paragraph that's going to catch people's attention once you have that and You have the introduction and those three steps and the sub steps you can write your conclusion and that will be like your call to action and I Have something I want to tag on to that that beginning paragraph It's kind of important to make sure that you're leading your readers in the right direction They know what to expect out of the article and you're not giving them anything like clickbait kind of stuff So make sure that you know That's why it's important to kind of do that at the end You know you want to introduce the topic because what if it's a 14 minute read? They're gonna look for some stuff and it's not there and they're probably gonna you're probably gonna lose your content consumer halfway through if some of that stuff wasn't in that in that beginning paragraph and Just to illustrate it. I took one of open source comms Which is still up so you can still actually go and see this an article a very recent article written by a men Sobo and He I don't know. I thought this was a very good template for getting started so he has his three intro paragraphs and He introduces his three Main points in the introduction and I couldn't screenshot the entire article, but you can see he Kind of To structure it and I included the link at the bottom if you want to check it out And I'll let Amy June talk about documentation Okay, so there's this website called indeed no big deal but according to indeed technical documentation is more formal writing style That describes the application the purpose The creation or the architecture of a product or service It's a little bit different than telling your story in an article There are many different types of documentation and we're just gonna list them for the sake of brevity We have tutorials We have how-to guides We have product manuals. Sometimes they're called man pages We have reference material We have project plans and in Drupal if we're lucky we have readme's Okay, so the Talking a little bit about the difference between the the articles and the documentation itself We want to be clear concise and succinct. We want to eliminate words We want to be careful of jargon buzzwords pop culture references and more specifically We want to eliminate those words that do not directly Enhance or support the purpose of your document design No sparkle no rainbows nothing. This is the point of technical documentation You want to have it be as clean and concise as possible and remember what something like Drupal were global market So the more concise we are the easier it is for everyone else the easier it is to translate and remember those pop cultures Terms or those buzzwords don't translate in other languages and cultures So you want to use specific nouns you want to words like things Kind of nebulous, you know, they should be eliminated from your technical writers lexicon lack of nouns Specificity Can be can cause confusion people are not quite sure what the point of your sentences. So what things specifically what people the sentence lacks meaning because of vague nouns and kind of forces the reader or the writer to add Extra sentences to clarify the confusion. So when you add when you don't specify your nouns No, you're no longer Concise and succinct We also want to strengthen verb phrases Verbs are the heart of your sentence, you know, it's that do action, right? When you water them down when you make them less, you know When you just you know, they kind of turn into mud so They get weak and they lead to confusion. So active voice And I struggle with this one active versus passive voice, but we always want to use the active voice when we're talking about Documentation and it's more accessible to use active voice Active voice means that the subject of the sentence is doing the action While passive voice means the subject is being acted upon We want to break up our walls of text. We don't want huge walls of text. We want to break up our content each point should be Brief and easy to understand so use bullet points or numbered lists They help to prioritize the information and break down those walls of text because you know Some of us are on our phone and we have those big long walls of text No one wants to read they want to scan so those bullet points are really important We want to make sure that we organize our content in a way that makes sense a logical flow. This is accessible to So to ensure that your documentation is clear and understandable. It's important to organize it logically This means presenting the information in a structured way that makes sense to your readers So you might have to refine this as you go and look down and maybe even have someone review it Do the steps make sense in the order? They are The last one is if your team has a style guide or like Drupal You know we have a style guide you want to follow that style guide You know you want to take time to familiarize yourself with it and reference it when you have questions it it really It provides those guidelines that you need for consistent writing and we don't want every read me to have a tone in a voice That's different. We don't want it to be in Chicago on one page and APA on another. Okay, and some accessibility tips that come along with With writing we want to define acronyms We want to define numerums and we want to define abbreviations So the first time you use I 18 and You tell it what it is put it in parentheses and then the next time you reference it internationalization You can do I 18 and accessibility a 11 y and Then you can put a 11 y throughout and the reason we do this is because it's not everyone is is privileged to have Some of those acronyms in their lexicon and BLM is that Bureau of Land Management or is it black lives matter? So little things like that We want to use predefined reading levels Usability gov recommends that we write at the ninth grade reading level But remember if you have a global audience your your reading level might need to be lowered We want to use clear fonts and avoid special characters And this is more for the technical writers sort of thing because in read means, you know, usually we render it as that's text but the Special characters and the last ones avoid emoticons and ASCII art goes along with these special characters Everyone kind of loves a good emoji, right? But screen readers love them a lot and they read every single one of them And so for someone like who uses a screen reader, it's annoying and it's just not necessary when we do our documentation I see a lot of people adding emojis in their read means these days and it's just doesn't make sense for accessibility doesn't make sense And it adds those rainbows and sparkles and things like that So some bonus tips we want to make sure that we write to one person We want to use singular. We don't want to do we or let's us We don't want to use pronouns We want to make sure We write as if our reader is doing the task on their own so no will should or could sort of verbs either write for one clear result This means teach persuade perhaps enlighten, you know on those technical articles one idea and Then try typing your topic into search to see what other people are saying about it, you know Just curious, right? And then we also say to use markdown So Marjorie's going to talk about some takeaways again sake of brevity. This is a little bit Abbreviated workshop. Yeah, and I'll also add to the the last slide about typing in your topic into search It's a great way to inform your headline to so How to use markdown That's a great headline because I guarantee you somebody has typed that into Google and it just increases your chances of your article being found but Five important takeaways Direct your article to the readers and not the curators so Don't do what I did with the passage Think about who it is that who it is is reading your your article and Just assume that like Amy June said that anybody is going to stumble upon it So somebody with tons of technical knowledge or somebody who is just starting out in their journey make sure that You're not assuming that Your people in your space are the only people that are happening upon your article Pose the question your article answer in the intro Make your point as succinctly as you can reference material so you want to back up any resources or any supplemental reading that will help further your your why or why you're writing and That just adds to your credibility And use proper grammar spelling and punctuation My managing editor was my hero because grammar is a tough one But it just again it just adds to your credibility and you don't want anyone to read your article and be like Well, there's a couple misspelled words it takes away from why you wrote in the first place and it can Distract people when there's a lot of that sort of action going on Okay, so Are we at time? Okay, so we're gonna talk a little bit about markdown and then we're gonna open up for questions I didn't do a whole lot of slides about markdown. I have a favorite Thing and I forgot to put it in there. I love to write tables and markdown So look it up tables are really cool. You can justify them. They Tables are scary for some folks, but they're really kind of straightforward to do again forgot to put it in here so Why markdown and I like to iterate on this a lot It's simple. It's intuitive. It can be converted to HTML PDF or other formats By using just a couple of tools and platforms that are pretty Standard across our industry So think of using markdown like you're using your editor without without using the buttons All of those whizzy wig buttons that you have you most of those that you can write and markdown So have you ever maybe y'all are more technical than me? You like submit a session somewhere and it's just a box and you're like, oh, where's the bold? Where's the whatever? Usually those boxes will take markdown So start with an MD file not a text file because an MD file is going to tell your editor how to render it so In Drupal 7 we saw a lot of readme's dot txt, but as we extend as we expanded How we wanted the formatting to go in the templates we now really encourage it to be in an MD file So MD helps read your editor render that out and markdown and The plain text files just don't allow that kind of formatting You know like the headings and the subheadings and the bolds and the italics and markdown format does They're kind of between a text file and a markup language like HTML. They're sort of that in between Know your flavor of markdown. There's a lot of different flavors of markdown out there Get hub has one flavor of markdown that may not work in a in a in a different editor So pick your flavor and kind of stick to it. I kind of think that these markdown Different types of markdown is like different dialects. I don't know why but they're just just different enough Find a good editor My best advice for folks who are looking for a good editor You don't need a huge IDE when you're a technical writer, right? But take your time and find out which one you like the best, you know, which plugins does it have which You know, how does it how does the UI look is it accessible to you? This is a list of Links so if you did get that link to the slide deck These are some markdown editors that I particularly write like I like VS podium a lot You know, it's a VS code but open source all of these are open source Joplin's a real good one Saw someone taking a picture. Did you get your shot? Okay, and then again abbreviated session. So these is me and Marjorie again are linked in and then if anyone has visual induced Motion sickness if you want to close your eyes, I'm gonna split back to the top of the Deck real quick, and I don't want anyone to get sick because I want everyone to have that link And we'll add more of those markdown. I'll do the whole table slides and that sort of stuff But does anyone have any questions for us? Sure Yes, so the question was what specifically do we talk about when we talk about special characters? So special characters can be m dashes. They can be percent signs. They can be ampersand Yeah, because screen readers don't always read them the same, you know, of course you have to have them sometimes, right? But if we can avoid using an ampersand when we can use the word and you know, and we you know Sometimes that the ampersand messes up your markdown too, right? You know, you got to eject the characters I have to have her with the question Okay, so the You're in Google Docs, and you want to in markdown? Okay, so there is an extension that you can use. Yeah Mm-hmm. Can I answer that one? So I'm more opinionated And I can talk about this for a long time Margie worked on a different website than I did enable architect and I worked on open source.com So for me open source comm we only talk about open source those machine-generated Words are not open source someone else owns that language. It's a tricky one. It's a very tricky one I've used it when I came into that question Our technical community advocate when chat GPT first started he could tell Yeah, that it was machine written. Yeah, you know, and that's the thing too, you know There's the as much as we say you don't have flavor. You do have tone and voice in a technical article So and and there was a lot of fact-check checking he had to do, too Which he does anyway because when we published we went through every single thing to make sure it was technically correct, but a lot of fact-checking You definitely could and the process that we use like Amy June said our technical advocate would just go through and be like Maybe we should reword this or But you know, there's another side to it too like the blank page is really scary so having that but knowing the wisdom To change it around and like, you know, they mean do that But sometimes it does help people with that first maybe the first paragraph or get to their point You know, they could be you can ramble into it and it will come up with something, you know, but definitely change it up It's a good idea starter and it depends on what you're doing It's a good idea starter and it depends on what if you are going through an editorial process as well If you're just writing this for LinkedIn It's a little different, but What I loved about our team was I could help somebody just they just had like a passage like I had up there I could help them Write their paragraphs like not write it for them But say like hey, just write a sentence and let's jump on a call or let's get on a Google Doc and talk about it But chat GBT is great or all the other processes It's great for getting the idea started, but it's not your voice and you just get better by learning how to do it yourself And and remember Most of our projects are open source So if you add some text, that's not open source. Are you open source anymore? So There's a lot of nuances so I Think Dave said we're at time. There's time for one more question Go John The user oh So the question is should I be using you and your To go on the singular and you really shouldn't use any kind of pronouns. It should be the user Can you use me? Can you even use like well? You shouldn't use pronouns you should like direct it to the just a general yeah Okay, yeah I think what in that case you could do both, but I would use developers personally. Yeah Yeah, you know you're being specific about the user to use this nebulous word right you're being specific about the noun and Yeah Does anyone need me to repeat that in the microphone? Okay, I Forget oh wrap it up Okay, so that's me and Marjorie Amy June Marjorie and Hey, if you want to do a long version of this workshop Drupal Camp Asheville is July 7th through 9th, and we're doing a three or four hour version of the workshop Where we brainstorm we come up with ideas we help you with your bios and pitches and it's really great