 and then just tell me when okay we're live hi everybody welcome to the technical talk for it's technically for the end of august beginning of september we'll have another talk at the end of this month and i'll be sending out announcements for that shortly today's topic is documenting wikimedia technical projects and your speaker for today will be me typically your host but today your your speaker so my name is sarah rodland and i'm a technical writer for the developer advocacy team at wmf my professional career i've been working for about over 10 years in open access and free and open software free and open source software movements both for and non-profit organizations i've worked mostly in operations and in technical writing positions throughout my career uh my education is that i have i have uh bachelors of organizational communication and writing and i have an mfa in creative writing uh in poetry and on fiction and the reason i like to share that is because that we do work in uh kind of a science technology field and um i just wanted to let people know that you do not have to have a science and technology degree to work in science and technology i also have some academic background in composition and rhetoric uh practical and research writing i've taught um classes and all of those things in the past so the reason i wanted to do this talk is because our in our technical community um better technical documentation is a consistent topic of discussion this isn't just across wikipedia or frost projects it's across software in general uh devs and technical collaborators are looking for clear and concise information to help guide them as technical organizations mature they need the need for good really good technical documentation becomes more and more apparent and necessary so we hear from collaborators in our movement that this is a need for them too uh we have a really well used tag uh in fabricator for documentation that gets a lot of use and um our tool for surveys consistently cite the technical documentation needs improvement and at every hackathon i go to um and in just in casual conversations with developers and technical collaborators across the movement i hear that uh we need improvement uh so the situation is is that uh the foundation currently employs two dedicated technical writers uh one's been here about a year and a half that's me and we just brought a brand new technical writer aboard and this is really a new area of concentrated focus for the foundation i did want to acknowledge that there have been writers in the past who've worked on our projects and done really good work and we always have really excellent technical writers in our community who work as volunteers so what i wanted to do today is just take some time to talk a little bit about what technical writers and communicators are and what they do how to get involved share your skills gain your gain some experience and then i also want to talk about some of our recent technical documentation that we have focused on for wikimedia projects um so there'll be time after the talk for questions over irc and on the youtube live stream and i'll add some uh and at the end i'll have a slide that has links to those that you'll be able to see those as well so this is what i would call an ancient talk page uh this is newspaper rock it's in the petrified forest in arizona um it's a rock with a bunch of pictographs on them made by ancient people that describe different parts of their world the way it functions probably just general graffiti um since the beginning of time humans have had a desire to share information especially information about how things work and why it's like the sun the moon the stars why nature does this or that how we were made the wheel fire whatever needed explanation this is all technical communication it is the language of what and how and it has been the hallmark of humanity forever so if we fast forward in time you'll find that our human drive to communicate the what and the how has not changed though scientific understanding of technology has evolved the ancient pictograph creators are now technical communicators who facilitate and move information through many parts of an organization or movement uh so in this talk i'm going to use the words technical writer technical communicator documentarian pretty interchangeably uh there are tons of different kinds of technical writers and communicators across science and technology i'll be discussing mostly what individuals who work in software do and then the other thing to note too is that the images that i use in this talk are all in the public domain and when i post the talk i'll have links to those in the as well um so basically at their most um at their most basic technical writers simplify complexity they take complex ideas and they present them in a way that their audiences can understand and i'll talk a little bit more about audiences later but i really wanted to say that technical writers make things simple um not to say that technical writers make everything simple they make information more understandable and easier to to replicate by an intended audience so technical writers have several areas of coverage that you might be familiar with um and some that you may not uh we typically and i've broken this down to three categories i think most people that think about technical writing think about technical writers as working on documentation and that is a huge part of their job in the software in software and technology what a technical writer will do is often they'll document products projects processes and progress for individuals working on technical projects uh software developers tool maintainers newcomers etc so those will be in the form of um different kinds of documentation and i'll talk about those little bit more later another job of the technical writer is communication so what they may do is they may translate complex technical material into information that non-technical individuals can better understand so this is a really important role for a technical writer because it they exist at the intersection of a lot of groups inside the movement and they're able to help facilitate communication on technical topics and help people understand things a little bit better another thing that technical writers or communicators might do is they might um participate in consultation so they may provide guidance and information for non-technical stakeholders to help them make decisions and communicate better with the technical community or partners or the general public so uh when people are maybe working on something that they don't understand so well technically a technical writer can help give them more information they can also do uh they can also they also have to know the right questions to ask uh people who are working with technology because a large portion of their job is to interview people and ask questions so where do technical writers sit in an organization uh in software technical writers are typically found in engineering department so at wms they might be in the technical uh team or the product team uh they're often part of a service team or a dedicated member of a team so uh in our organization technical writers are dedicated members of teams i work for dev advocacy our newer technical writer will be working for court platform in some organizations it's a large group of writers who work and serve the the groups as a team they can also be found in marketing and communications um or sometimes even in sales or customer service so in the last org that i worked in i actually worked in the customer service team because i did a lot of work facilitating communication between our customer service reps our institutional clients who were librarians and then our developers who are creating products for those librarians and so that made um that seemed like the most uh the best place for me to sit in that organization so you may find technical writers anywhere and uh so i have this little graphic up here which is kind of just shows like where technical communication sits in the middle of a bunch of different teams and processes and ideas within our organization um technical writers can see themselves as an kind of an interactive group that moves information through parts of an organization uh it connects them together um to make sure that the right parties are aware of the right information um and so i also think one of the things that you can think about is that technical writers uh are kind of conduits for information flow they connect the dots for others uh my kind of my big joke is i i love tech being a technical writer because you kind of are also in the middle of all of the gossip you know what's going on with different teams you know um you have a lot of information about what's going on the organization and you can be really helpful uh when you're sitting in the middle of all of that to help people connect people with each other and tell tell different stories sorry that's my if you guys hear that i have a little mindfulness bell that just went off so what do technical writers produce so you have a technical writer an organization you know that they have different areas of coverage you know that they sit is a nexus of communication between many different groups uh what are their kind of what is their end product though what do they make um so i wanted to cover some of the things that technical writers actually make and produce in the organization so when you see them you can say oh this is something a technical writer did so again i think our most typical idea of what technical writers do um and is produce documentation so when you're looking at how to's or walkthroughs or tutorials um those are written by technical writers whether they know they're technical writers or not uh read knees are technical writing um any kind of help and support content uh technical and design specs um project plan system documentation user manuals api documentation and so much more uh pretty much anything that's written that's technical that's helping to explain things to other people that's going to be a form of technical documentation another thing that technical writers work on a lot that um we might not really think about so much is they work on processes so uh technical writers create and document processes uh they spend a lot of time observing how things work uh evaluating how they work thinking about how they could work better or more efficiently uh sometimes they will create processes sometimes they will oversee them and help others create them uh they do a lot of troubleshooting um they ask things like does this make sense does it work if i follow this can i do it again um they'll ask others to try and follow a process too um and then they write it down and they test it and they revise it so just a huge portion of the role is um is thinking about how things function how they work how they process um i always joke that i'm a person who really just loves uh things fitting perfectly into things and so for me this is a really great role because um working on process is one of those things where you can really um smooth the path for other people and make things fit very well and then another aspect another thing that of technical communication is uh communication so along with creating documents that help developers or technical collaborators technical writers will often create documents that help other people understand what they're doing um so they may write technical blogs they may manage social media geared towards devs or engineers or just the general public so they understand what's happening uh they may do things like review write give speeches or talks on technical topics like i'm doing now um they often will do seminars or webinars for um uh large groups of people uh if you're working a for-profit organization they'll do those for customers a lot of the time or for potential customers again they'll work in marketing and outreach and they also do customer help and documentation uh one of the things that um they also do that i didn't put on the slide and should have is um they do a lot of communication around feature changes incidents and outages so this is something this is a place sometimes where development or technology and um end users can really kind of collide a little bit um if there's an outage or an incident and um people want to know why that happened a technical writer can be really instrumental in helping people understand a little bit better how things happened when they'll be back up again or they can help communicate change changes to features uh for people as well so i'll go a little bit now into how technical writers decide what to write uh i think that there's um a misconception that technical writers just kind of say i'm going to work on this thing and then um or there's this thing i need to document and then they just sit down and write but there's actually kind of a process behind it and there's a lot of thought that goes into uh what and how they decide to write so one of the first things that technical writers think about um most importantly is uh who their audience is um they everything that they do depends completely on the audience and who they've been asked to communicate with and how they want to convey it uh knowing the audience helps them know what is appropriate to share and how to share it when a technical writer sits down to write uh who is this for is among one of the first questions uh what do they need to know how do i share this message in a way that they will understand it so for us technical writers audience is always at the front of our minds uh the next thing that we think about is um the purpose so along with the audience we have to ask ourselves uh why are we sharing this message a lot of the time we um are tasked with creating a piece of documentation um it were probably really annoying because we'll say who is this for why am i writing this and we'll ask this over and over again but knowing the purpose uh right away um and the reason for communicating will really help determine the format um and then typically i think the purpose can be broken down into um these four really basic categories um to learn uh to achieve a goal to understand and to inform and what you choose to create based on those will be a little bit different um to learn might be something like a walk through or a tutorial that can also go into achieve a goal if you want to um do a very specific thing you might also create a walk through a tutorial for that uh to understand might be more explanatory it might be the history of a thing it might kind of walk you through um different aspects of a of a certain thing and then to inform might be more like reference material so it might just be tables that you're that you're looking at you just need to look up very quickly and so you have different purposes for the information that you're or you need to know the purpose in order to design the information for your audience and then the other thing that we look at a lot or think about a lot is the context or the situation in which um that writing is going to take place so um I always think that this is a little bit trickier to think about then audience and purpose often you know who you're writing for you have a little bit of an idea and the reason is pretty clear but the context can be a little tricky so um it kind of like this explanation or I kind of like this imagery because it's really it's really helpful in understanding that a little bit so on the one side you have um some folks in uh having their hair done and then the other side you have a doctor explaining something to um to a couple of people so we know that the context for the situation the hair salon is going to be different than the context of the doctor explaining information to uh uh in my mind I think it's a father and a daughter but um in your mind it might be something else uh and so we know that the context for the the salon is going to be super informal probably uh and they may use a lot of slang with each other they may talk back and forth like they may have a very easy conversation so if you are a writer writing in that context the kind of language uh idioms like things that you choose to talk uh to talk in that situation are going to be very different than if you have the context where you have a doctor explaining uh medical information to uh to a family and so that helps drive the decisions that you make when you're deciding to write uh so I always think about you know when I sit down to write technical writing I think about how yes I have a message to convey I have a certain audience of developers or engineers but um I also work in the context of this really big volunteer project that has a lot of history uh and I want to keep in mind that there are constraints and rules in the back community um and then I'm also limited by my tools the tools that I use uh might be different if I were working in another kind of software we tend to want to use free and open source software in um when we're working on movement work um so that's going to be a little bit different that's going to contextualize things a little bit differently um and then I think about things like uh you know how am I going to design this so that others can come and work on it later and then also you know this volunteer movement has many many languages uh and people at many different levels of um of um of English proficiency so if I choose to write in English the context of the English language how am I going to write in a way uh that my audience can also translate that so context can be very small and it can also be very big but it's really important to think about when you sit down to any writing task uh so this slide I think is a really good illustration of the writing process uh again I think sometimes in our minds when we think about a technical writer uh we think oh hey they have a thing they're going to document they sit down and um and then they just write it and then it's kind of done and you know I think sometimes we do that when we're writing uh just things on wiki where we might say like I just need to get this down and then it's published and it's done uh with technical writing there's a little bit more of a process uh so what we do um a large portion what we do that's not writing is we're planning so uh we define that we have an audience of purpose in the context and then we start to think about now that we know we need to to write a thing or create some communication we begin to define requirements we also conduct a lot of research we do interviews and we'll outline the project so this might actually take a large a much bigger slice of time uh than other other parts of the project even writing or drafting the project so after we've planned and we feel like we're in good shape to get started uh we will create an initial draft uh and then I have a little feedback loop here because uh especially working on wikis this the review and publish can um can and are kind of uh circular feedback they kind of move around so um typically after you create a draft you'll review it you'll test it revise it uh you might run it through other editors you might run it through um other writers to look at uh and then you publish and share the content so we know on wiki that um often we'll create an initial draft we'll publish and share content that's when it'll get reviewed tested and revised uh then we will work on it again um that's really like the benefit of having a huge uh group of volunteers and folks who can come in and make things better and better as they go along the other part of the process that um often gets neglected but that we really need to think about is maintenance so uh you know often people will work on something and publish it it'll be reviewed it'll be up and then it's done and they walk away uh but another really critical part especially in technical writing is how do we maintain that documentation uh what is you know how do we know that this is relevant and that this content will be sustainable uh for the future um and this is really something I think is a movement we need to work on uh better too because I think a lot of times we do in the moment create um and publish and then we're not really revisiting until until much later so um we talked a little bit about what technical writers are and their area of coverage um and then you know how they a little bit about how they process and and um how they work um and what I want to talk a little bit about is measuring the impact of technical writers so um Tom Johnson he's a technical writer in the in the bay area um and he's pretty well known for writing a lot on the topic and he says that the knowledge assets that technical communicators create have a value that can be hard to measure so measuring impact is actually uh pretty difficult uh there's not at least right now especially in the work that we're doing with the movement is um there's not really a metric or number or percentage uh Tom Johnson also calls uh technical writing or knowledge the lifeblood of an organization so we we know it's important but we just don't know always how to measure that importance um we can tell when something's bad or it's not working because people let us know that um if it's working rarely do people uh write uh on a talk page and say like this documentation's great I love it uh never change it um and if it's bad people don't usually say like this is bad but the writing's really good um you know so it's it's a little bit hard to measure that so instead of really thinking about impact in terms of numbers uh or percentages or I tend to think of it more in what are the benefits of having technical writers and communicators working on projects uh and I and I'm not a person who really likes to say it's good for the sake of good so I like to think more about well what are the things that they do that we know are going to have a positive impact on on our projects so we know that they facilitate communication between groups of people that's you know inside WMF uh between volunteers between volunteers and staff different um different kind of technical groups and people who are less technical uh they help set standards and help keep communication consistent so um one of the things that you know we're working really hard as um technical writers at the foundation to do is to start to set some standards uh and make it a little bit easier for people to know um what are the best ways to write documentation what are the ways that we can keep it consistent uh so it's easier for others as they come along um their work supports users at all levels and across all projects so the work that technical writers do it's you know it's for everybody um and they close knowledge gaps for new people trying to participate in our projects so I think that this is a really important one that's why I put it in bold uh good technical documentation has the power to be an invitation to people uh if people feel that they understand what they're looking at uh or if they can follow instructions clearly it gives them an opportunity to make entry into some of our projects that might be a little bit more difficult for them to join if they're not well documented um another thing that it does is it reduces the one-to-one knowledge transfer um between people so it increase it increases continuity of knowledge and um basically what I mean by that is instead of having to go directly to a person and ask them knowing that they may have information and they can help you um our hope is with good technical documentation that we're able to have that out in the open for everyone to look at so that they don't have to keep going to the one person who knows or if the one person who knows um leaves or decides to stop volunteering um they're able uh they're still having a there's still some continuity in the knowledge uh so technical writers I think that they add value rather than they take value uh it's not going to hurt our projects to have more technical documentation and that value um I think it produces more than it costs us to to go through and document our steps and what we do um the other thing is I I call increased audience satisfaction and basically what this means is that uh when people visit our projects and they encounter communication that speaks to them and they feel included uh and they feel like they understand what's going on they're going to be much more satisfied than if they encounter say a page that doesn't make sense that they can't read very well um they can't translate into another language very well uh or that they can't follow the steps or the information doesn't work uh that can really color their um their experience uh again support cost it saves time and I think that goes back to that one-on-one knowledge transfer um and then it reduces training development costs and then just overall cost of information development so we know the better documentation we have the less we have to develop um the less cost it is for the organization and for our donors so um I talked a bunch about what technical writers do what their benefits are um you know kind of a little bit how they work and I just want to talk about how you can grow as a technical writer so one of the things that I like to tell people is that you know if you've ever in any instructions any directions if you've ever written a read me or contributed to one um you are already a technical writer so you have already taken the first step I think we all are a little bit technical writers but you definitely have started to do the work and if you enjoyed it or you want to learn more uh you should definitely try to gain some experiences and skills so uh here's my list of useful skills to have it's kind of a long list and you don't need to have all of them uh but these are these are things that you can work on so the top skill um that I would say you need as a technical writer or communicator is compassion and empathy I know that this isn't something that we always talk about a lot in um the technical field but as a technical writer or communicator you're going to constantly be talking with people asking questions and trying to communicate a message to groups of people that you might not understand very well and one of the things that you need to be able to do is empathize with them um and understand what their situation is and why they might need the information that you're sharing and how you would share that so uh in terms of um in terms of the work we do I do actually think this is the top skill that you can have uh the other skill that you would want is the ability to collaborate with others online and in person I think in the movement we have people who are very good at doing this so um so yeah you're already you're already there and then writing and editing skills I wanted to put a note here um that you don't need to be perfect at this uh I know that there are a lot of people that pride themselves and being great writers or great editors uh but we all make mistakes we're not perfect um we're all learners and so this isn't actually something you should worry about too much this is something that you can work with with collaborators um that you can learn as you go we all have different quirks in our writing um that we can kind of work on and and play with and learn from uh interviewing and research skills uh the ability to learn so if you do technical writing you're going to be working with so many different people and technologies and there are going to be days when you feel like I understand all of this and there are going to be days when you are completely you encounter completely new concepts that you have to figure out very quickly because it's your job to make sure that other people who don't understand those concepts will understand them better uh the flip side of that is that you have to be comfortable with not knowing things and you have to be comfortable um or not understanding things and you have to be comfortable um verbalizing that as well so as a technical writer there's no faking it till you make it you really have to be able to say I don't understand this concept please help me understand at a very low level how this works or I want to understand this better um on this list I also have some other skills in terms of different kinds of languages programming design programs things that you need to might want to learn or know again just like writing and editing skills these are all things that you don't have to perfect that you don't have to know all of this before you can become a technical writer these and these will vary between all the projects you're working on you may be using totally different tools in totally different projects if you're working in free and open software or if you're working in proprietary software the tools could be very different so you know just just get started is what I would say and start working on a little bit at a time at the very bottom that I have here is understanding of agile software development process and I will just kind of say without going too far that if you're a writer this is going to be a really natural for you because part of the job of a writer is to write and then rethink and write again and to write and rethink and write again and so you're constantly moving getting things better thinking about what will work in that moment what's going to work just in time for this thing and so as writers this becomes a really this is a really natural a really natural area to work in so I'll have what to study here so again you know I think in my first slide I said you know I have an MFA in creative writing I don't have a technical degree it can be useful and if you're going if you decide to study technical writing or computer science you know I just want you to think about that a little bit that that there are different routes and different ways to get here if you are working on a degree computer science writing of communications is really good there are technical writing certification programs I have in the US here just because that's my area of knowledge I'm not sure what's available globally so that might be if you have a degree already and you want to add an extra certificate to it there's a group in the US called STC which is the Society for Technical Communication which is kind of big for technical writers and communicators here and they also do a certification too but I'm going to say like Wikiversity has a great technical writing program that you can look at it's a good start you can learn a lot from it I definitely reference it a lot myself and there are plenty of online classes and groups and things like that that you can join and then the best thing that you can do is really gain experience so you can work on technical technical documentation for open source projects you can work on wikimedia or media wiki projects you can work on other FOSS projects GitHub is a great place to explore there are outreach internships that we work with specifically at the foundation and the last few of ours have been focused on technical writing we're just working on Google season of the docs I'd encourage you to look that up as well that's also an internship program that folks can work directly with technical writers at wikimedia and other organizations to help make their projects better and then I also write the docs here as well which is a also worldwide meetup group for people who are interested at all levels of the field it's very open it's very radically inclusive so it's a great place to get started if you're trying to learn and then I also have a link here to some outstanding tasks I said earlier as well that our fabricator board we have a documentation tag and it's huge so you can always browse through that you can always ask questions you can always reach out and our resources are getting are starting to get better and better for this and so with the time that I've left what I want to do is just talk a little bit about some of the work that we've been doing specifically to improve documentation on wikimedia projects so basically I want to say the first thing that we've done number one is that wikimedia has started to recognize that technical documentation is a very important aspect of engagement for technical collaborators especially new and potential technical collaborators so I think that's really important just acknowledging that this is a big thing this is something that we need it's an important aspect of reaching out to our collaborators and being a part of a community and then just also acknowledging that we have a need and there's a value for having some professional professional technical communicators on staff to help so in the last year and a half we recently added two full-time technical writers one and have advocacy that's me and then again a new a new writer that we have on court platform so we have been making changes and we should be seeing changes coming coming along so you know we understand that teaching mentoring and learning from new new technical documentarians is as important as simply creating technical documentation for software developers and our ethic is that our work is done in community so we try to do as much of the work of technical documentation in community with volunteers or with interns or with members of our technical community and so in the last year we've done a lot of work to update our technical documentation style guide we're partnering with google season of the docks right now with an intern who is further improving those resources and we should see more of those coming out in the next couple of months she's done some really great work and i'm super excited about that this last year we worked with outreachy to update and refresh media wiki action api documentation so that was really cool too we were able to work with a few interns on this and have a few rounds with this and so the media wiki action api documentation has been greatly improved over the last year we've partnered with academic institutions and student writers to evaluate and improve technical documentation on wikimedia projects i'll talk a little bit more about that in just a second and then we've also attended a lot of conferences and hackathons and writeathons and we brought tasks for documentation to writers at varying levels so we've been working with writers in the community to see what they're interested in and also to kind of gather some of their help to work on some of these projects and then one of the big things we did too is we rebooted the technical talks which is what i'm doing right now just to provide another forum for the technical community to document and share information and then we're currently working on a couple of initiatives to better partner with the technical community and improve technical documentation globally across wikimedia projects for the past year or so we've been working on a technical writing special interest group i personally have enjoyed it because we've been able to surface a lot of issues but i'd like to see a little bit more engagement from the community we have a lot of staff on that on the on that sig and so one of the things that we'll be looking at in the next couple of quarters is changing that to something we're calling friends of the docs that's a little bit more open hopefully and has a little bit more community engagement and then we're also focusing now on some more of our technology that the community works with quite a bit which would be wikimedia cloud services and specifically tool forage documentation and then cloud vps documentation so we do an annual survey and our users consistently identify a desire for better documentation for these services and so we're focusing on that now and now i'm going to go over tool forage improvements super quickly because yeah so i just want to drill down a little bit and look at a really specific content collection we're working on which is tool forage again it's something that the community's expressed a need for consistently for better documentation and we did start some early efforts in 2017 and this is part of our working with community effort we did an audit of the technical documentation with some graduate students at boise state and what this resulted in was a set of global recommendations for improving the organization and quality of content on that content collection and then we used this page views tool which basically allows us to see which pages are being most visited and it helps us understand which has the most traffic and then it helps us priatories which ones to improve first we did this as well when we did the when we did the work on the media wiki action api because we're our resources are really limited we just kind of have to determine what what is getting the most visits and the most visibility and start working there first and that seems to be pretty successful strategy for us so the first phase of this is just working on developer maintainer documentation this is really the documentation that every all the technical like technical collaborators who work in tool forage are using the most and these are the pages that see the most traffic on wiki tech uh so if you think all the way back to the beginning of the talk where I talked about audience context and purpose this is kind of our quick way of defining those before we start writing if we're doing a fast or quick writing task or really just sitting down to write in the moment or have kind of an overall strategy for writing we'll create these developer stories and this helps us these small snippets help us determine who our audiences and who their needs are so for tool forage documentation we sat down and decided on these developer stories and i'm not going to read them all right now but these are basically very quickly who's using our who's using our using tool forage what their experience is and what they want to know and from that that'll help us drive what we're what we're going to change and then because we don't have a lot of resources for for user research or or really like a deep understanding of our audience at this point one of the things that we want to do is do some overall changes that are kind of global best practices and then once we get those in place then what we'll do is is we'll be able to have some better documentation or some cleaner documentation that we can start testing with audiences so i'm going to go through these super quickly these are the things that we're looking at when we're improving doing the initial improvements to tool forage and these are things that you should start to see changing on wiki tech in the next they have been changing and they will be changing as we're moving forward forward so one of the things that we look at site organization we just look to see you know does it have the same sidebars they have bars footers are the recurring links the same is the site consistent can people find their way through it is like content grouped with like content when we started this project they made a map of what tool what wiki tech looks like and we can see that some of the information is siloed in different places and so one of the goals of the improvements is to change those silos the other thing that we are looking at is page organization this is something that we hope filters across all the projects documentation which is just that users will have a consistent experience between the pages and that pages follow a consistent template that seats the purpose of the content so this is something that we did with the media wiki action api documentation we determined a template that was going to be consistent across those pages and easy for our for the audience to navigate and we're doing the same with wiki tech as well and then we again we want to just make sure that all of the elements of the page are the same and then we think about readability so we want to make sure that style and tone are consistent across everything that the language will be simple I will go into this now but there's this idea of a flesh concave score we want to keep that kind of low so that we can make sure that users can translate it or understand it and then we want to make the sentence as short and concise so a lot of the work of improving tool forage documentation is just simplifying language and then we want to think about memorability so we want to make sure that the content is organized and written in a way that aids long-term memory and learning over simple reference one of the things that we don't want is we don't want users experience of the documentation to be quote-unquote bad because that's really going to be their memory of the documentation as opposed to what the content is and so it's really important to create a good user experience so that they're prepared to remember and hold on to that material and then we are looking to see if the content is still relevant and correct and if it's not we want to correct that we want to update or we want to remove any outdated or relevant information and fix what and then change it if we need to and then the last thing which is a challenge and I'm definitely thinking through and would love to hear a lot of thoughts on is once this documentation is in place how do we make it maintainable and consistent over time it's not something that we just want to create and then leave we want to make sure that it's something that you know has a good isn't a good place and that the community can continue to maintain it for as long as it needs to be maintained so our next steps are finishing the improvements the initial round doing user testing for accuracy and readability thinking about if it fits user needs we want to look at the UX and design also for better readability can we change the page structure how do we make it how do we create it in a way that it aids readability and and surfs the content better and then we want to think about continuous improvements how do we maintain the technical documentation and make sure it stays high quality and then the next phase of tool for documentation will be working on administrator documentation so this will be another another part of wiki tech you can follow improvements here i have a couple of links i'll post these afterwards for folks to look at and then it is time for questions and i have a slide that has links to the youtube stream and all of that so thank you thank you sir i don't see any questions right now um but i would like to say that i learned a lot about technical writing there that i will definitely use in my job so thanks awesome maybe we can give it uh 30 seconds or so to see if anyone has any questions before we shut down perfect yeah subhu says he had a meeting conflict but he will be watching the recording oh perfect yeah oh and i should also mention uh feel free to reach out to me um either an irc or you i really think on everything so if you can find me and you want to ask me a question uh it's really fine you can email me you can you can get me an irc you can get me in hangouts if you have my hangout um i'm also on telegram and a couple other uh i'm on zulip as well so um you know i guess staying true to being a technical communicator i just want to be everywhere um but if people have questions or i think especially about um you know how can they participate how can they join in uh how can we better support people because that's uh i think in my mind having our community really feel supported in doing the work of technical documentation um that's really big so um you don't hesitate to ask questions you can also send um general questions to wikitec l we monitor that too and uh and we're we're happy to answer any anything cool so we had a couple questions pop up so Diego asks uh what would the what would be the main difference between technical writing and academic paper writing oh well i think the basic elements are the same so i would actually say probably i'm thinking about this on the fly uh when you think back to that uh i call it like a rhetorical framework um that audience context and purpose they're going to be different so that's going to change the way that you decide to write so your audience is going to be um academics probably not developers the context is going to be in an academic environment and uh Diego you're probably pretty familiar with like the with that like there's a there's a whole other context that um and so your writing is going to change based on on that kind of rhetorical framework but the basics of writing and communication are the same across whatever field you're working in so um that's why you see a lot of creative writers doing technical writing for careers later on we're working on content or um teaching or even writing or presenting academic papers does that answer your question yeah it looks like he followed up and was uh he was this question was in terms of writing style so i think i'd address that yeah yeah uh and then someone on youtube says um thoughts on simple wikipedia or dictionary um are they i guess i would need to have a follow-up question with that um are they saying in terms of language uh in terms of technical documentation um or style uh basically what i think more specifically uh what what they want to know okay yeah we'll see if they follow up on that they say uh in terms of language do they share the same goals um you know i'm going to do the technical writer thing where i'm going to say i'm not sure i know enough about the specific projects to know um but i will say in terms of our overall goals as i think wikimedia projects um i i will always favor more simple language just because we have such a wide audience but i imagine that our projects have very specific audiences or specific groups of users that use them uh and so that's kind of my short and long answer but i think i don't have enough um deep knowledge of those two particular projects to to provide a super comprehensive answer all right so i think that's all our questions um cool awesome well thank you everybody and uh we i'll post all of these slides to um to the tech talks page and then if you have more questions feel free to reach out to me and i will try to answer them for you and then um i'll be announcing our tech talk for later in the month i actually think it is Diego that's doing that talk um and then um and then also i really invite folks to uh do a tech talk themselves um this is doing it today myself has been really informative and i want to think about some structural changes to how we do them or give more options for people uh but this isn't only a staff thing this is also for community um everyone in the community and i want to make sure that people feel uh supported that they're able that they you know they're able to share information if they want so uh i'm definitely here if you have questions about tech talks or you're thinking about doing them um even you know just thinking uh feel free to to reach out and uh and we'll try to work something out so that's my spiel