Keynote: Docs or it didn't happen!

Video in TIB AV-Portal: Keynote: Docs or it didn't happen!

Formal Metadata

Title
Keynote: Docs or it didn't happen!
Subtitle
(with Q&A)
Title of Series
Author
License
CC Attribution 3.0 Unported:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Identifiers
Publisher
Release Date
2019
Language
English

Content Metadata

Subject Area
Abstract
Have you ever skimmed through a README, tried to follow a quickstart tutorial, attempted to decipher an error message, or typed ‘–help’ in your console? Congratulations – you have encountered documentation! Long gone are the days of massive books with never-ending stories about your software. Today’s users are smarter and less patient, which means that we no longer need to document all the things, as long as what we do document is clear, concise, helpful, and accessible. And that’s where the real work starts. Documentation requires some attitude adjustment, since prose doesn’t neatly compile into binaries as code does. But Don’t Panic™! No matter what your role is in the community, you can apply a few key principles from the technical writing world to make your project more docs-friendly, and therefore more user- and contributor-friendly. This talk covers strategies, best practices, and pro tips for rethinking how we create and curate documentation. This special edition will include Django-specific examples and use-cases as well as a special Q&A session, where we will try to address some of the community’s top concerns and ideas about the Django docs. Special edition: Send me questions before the talk, and I will try to answer them on stage. If you have a twitter account send your question here. Otherwise, you can email me at docs@docsideofthemoon.com. Don’t be shy!
Laptop Email Presentation of a group Open source Multiplication sign Shape (magazine) Mereology Shift operator Computer icon Twitter Internet forum Core dump Quantum Computing platform Email Software developer Projective plane Stack (abstract data type) Open set Data management Software Sheaf (mathematics) Video game Right angle Reading (process) Spacetime
Vacuum Presentation of a group Software developer Multiplication sign Planning Bit Machine code Software industry Content (media) Mereology Neuroinformatik Type theory Word Strategy game Telecommunication Strategy game Right angle Writing
CAN bus Data management Process (computing) Software Strategy game Telecommunication Software developer Software Cycle (graph theory)
Inheritance (object-oriented programming) Validity (statistics) Order (biology) Strategy game Content (media)
Laptop Game controller Touchscreen Key (cryptography) Projective plane Set (mathematics) Bit Plane (geometry) Software Personal digital assistant Right angle Quicksort Reading (process)
Context awareness Code System administrator Multiplication sign Sheaf (mathematics) Set (mathematics) Water vapor Coma Berenices Mereology Formal language Fluid statics Different (Kate Ryan album) Computer configuration Continuous track Diagram Error message Email Touchscreen Software developer Web page System administrator Electronic mailing list Bit Type theory Message passing Repository (publishing) Volumenvisualisierung Website Configuration space Hill differential equation Right angle Summierbarkeit Cycle (graph theory) Reading (process) Point (geometry) Open source Link (knot theory) Software developer Patch (Unix) Online help Shift operator Touch typing Computer architecture Fingerprint Home page Dot product Shift operator Information Online help Weight Projective plane Content (media) Word Wiki Software Personal digital assistant Cube Table (information) Fingerprint
Web page Group action Overlay-Netz Link (knot theory) Multiplication sign Electronic program guide Frustration Web browser Shift operator Formal language 2 (number) Causality Different (Kate Ryan album) String (computer science) File system Boundary value problem Information Error message Computing platform Overlay-Netz Shift operator Information Bit Radical (chemistry) Word Message passing Arithmetic mean Root Exterior algebra Software Personal digital assistant Function (mathematics) Right angle Routing Physical system Reading (process) Resultant
Common Language Infrastructure Trail Group action Open source INTEGRAL Code Interior (topology) Connectivity (graph theory) Patch (Unix) Multiplication sign Disintegration Source code Ultraviolet photoelectron spectroscopy Set (mathematics) Real-time operating system Online help Open set Content (media) Stack (abstract data type) Mereology Software bug Neuroinformatik Strategy game Different (Kate Ryan album) Hierarchy Flag Energy level Data structure Computing platform Task (computing) Source code Validity (statistics) Gender Video tracking Projective plane Content (media) Code Bit Continuous function Hierarchy Word Software Repository (publishing) Personal digital assistant Software repository Right angle Game theory Family
Different (Kate Ryan album) Multiplication sign Electronic program guide Data conversion Sequence
Code Line (geometry) Chemical equation Binary code Code Disk read-and-write head Software framework Website Software testing Convex hull Right angle Gastropod shell Block (periodic table)
Goodness of fit Process (computing) Open source Computer file Block (periodic table) Projective plane Interior (topology) Formal grammar 1 (number) Software testing Sequence
Presentation of a group Code Multiplication sign Range (statistics) Open set Mereology Formal language Strategy game Different (Kate Ryan album) Kernel (computing) Modul <Datentyp> Software framework Physical system Collaborationism Block (periodic table) Software developer Menu (computing) Bit Connected space Type theory Telecommunication Software framework Software testing Right angle Modul <Datentyp> Procedural programming Quicksort Block (periodic table) Reading (process) Writing Web page Point (geometry) Trail Mobile app Service (economics) Open source Computer file Patch (Unix) Electronic program guide Online help Event horizon Template (C++) 2 (number) Number Frequency Ranking Software testing Task (computing) Computer architecture Module (mathematics) Scaling (geometry) Validity (statistics) Projective plane Content (media) Code Planning Machine code Cartesian coordinate system Kernel (computing) Event horizon Personal digital assistant Gastropod shell Routing
Context awareness Group action Presentation of a group Open source Multiplication sign Collaborationism Water vapor Heat transfer Twitter Attribute grammar Formal language Revision control Damping Process (computing) Category of being Formal grammar Area Context awareness Texture mapping Projective plane Heat transfer Infinity Maxima and minima Category of being Word Keilförmige Anordnung Googol Process (computing) Software Revision control Formal grammar Right angle Figurate number Object (grammar) Data structure Writing
Group action Code Orientation (vector space) Multiplication sign Execution unit Set (mathematics) Mereology Perspective (visual) Computer programming Bookmark (World Wide Web) Coefficient of determination Bit rate Different (Kate Ryan album) Modul <Datentyp> Flag Process (computing) Hill differential equation Enterprise architecture Collaborationism Software developer Feedback Arithmetic mean Process (computing) Telecommunication Website Modul <Datentyp> Figurate number Data structure Task (computing) Reading (process) Point (geometry) Dataflow Open source Software developer Feedback Collaborationism Lace Vector potential Template (C++) Wave packet Goodness of fit Telecommunication Hacker (term) Software Queue (abstract data type) Software testing Task (computing) Scaling (geometry) Information Projective plane Content (media) Heat transfer Code Planning System call Vector potential Peer-to-peer Keilförmige Anordnung Error message Software
hello everyone it's a really great to be here this is my second during a con erupt ever the first one was in two thousand sixteen in budapest and i was not able to enjoy it as much as i am enjoying this one so it's really great to be back on today we are. going to talk about dr didn't happen which is how i can live my life i hope to see more docs talks next year but let's see right so why are we here here as in in this room not on this planet this is not an existential question why are you sitting here in the stock because we want to have more.
users more contributors we want to increase adoption of our open source projects and we're hoping to believe that documentation can help us but something something is stopping us from writing documentation so this is a very special edition as sarah said of the stock in this is only something that i would do for. django community which is i'm going to take questions because i never take questions and i did get some questions in advance on twitter so i've already incorporated these into the end of the presentation and i'm also going to encourage you to write your questions on slack there's a questions channel on the slack and we have a great. a moderator for online questions and then if we have time at the end maybe i'll let some people come up to the microphone but we will see the reason i know when the reason i don't normally take questions is because most of the questions are best answered when you ask me face to face and when we have a laptop with us right so a lot of the stuff is i have this read me it's in. really bad shape how can i fix it i can't really answer this from the stage right so i do i encourage you to come and talk to me afterwards right to me on slack twitter e-mail i'm here for you so who am i as a day said i am that docs lady i have been for the past five years or so i have been a technical writer for about two. ten years but five years ago i joined red hat i live in prague i work at red hat document open stack platform which means i read a lot of python and i used to work in containers and i kind of play with them like this. and like most of us before that i was working in the java space also are covering scrum master and i still love agile and develops really do i am on the core team community management of right the docks together with my friend says her mind and to other people and if right the docks sounds like. creed the docks to you that it's because it was started by the same people so air culture is the co-founder of both right the docks and read the docks and it's a wonderful community built and open source principles specifically built and django and python community values which is part of the reason i really love it. django girls alumni stored in his workshop in czech republic and i roam around icons and jenkins in around europe coaching developers on documentation running docs friends i was very fortunate to join django under the hood for few years to run sprints. i'm also contributing to fedora annum the co-author together with sasha of the happiness packets project which has nothing to do with technical or software has everything to do with being nice to people so i highly recommend you to look it up i have stickers for most of these things in the front and also in my bag so what am i going to talk about.
a the main parts of the presentation are going to be content strategy which basically means think before you don't work which i hope you're also implementing in your coding. so it's the same thing plan a little bit save a lot of time and aggravation later develop stocks because when i first started working as a technical writer we used for a maker which is a very microsoft word the type of thai season has not been yes i'm so happy that we don't use that anymore and elk x.m.l. came along and everybody was happy. now xmas going away and everybody's even happier so i've seen the the technical spectrum of of the technical writing world changed drastically in the last ten years there's a lot of cool stuff happening there and the last thing is the community spirit because we do not work in a vacuum and we are all in this together.
so i would like to invite you to join the documentarian clever currently populated by computers and humans and what is a documentarian a documentarian this is from the right to docs manifesto documentarian is someone who cares about documentation and communication in the software industry.
regardless of job title ok so it's no longer tech writers developers you know designers everybody can care about communicating in describing the the software regardless of job world so we're all documentarians uk doesn't matter if your community manager if your support engineer everybody can.
have something to do to make this a better place as the same as were all involved in the software development cycle in one way or another. i. so condon strategy means asking the right questions.
ahead of time and i'm going to.
give you a slightly different way of thinking about this ok because this is the kind of strategic thinking about documentation that i have to deal with a lot when i work with engineers at work for example because i often find that for some people when you create a tool when you make software and. you send it out to the world then you want to tell everybody everything about it you know so much like this existential validation you know when your child and you show your drawing to your parents if they don't acknowledge it means that doesn't exist right so we're trying to change that way of thinking where as you no longer think of this as what is it. and for me is what is in it for my readers and my readers are many users and k. so i want to create value in the documentation i don't have to document every single thing anymore which is quite nice actually so i'm going to use the five w. questions why who what when and where probably in this order.
i can remember. so why do i need to know this is the first thing that you should consider why do i care about the documentation that i'm reading which is exactly the same question is why do i care about the software that you're trying to get me to use right so if we're thinking about this not from a hey this tool can do all this cool stuff. of his ask not what your to what your tool can do for you is what you can do with this to ok so it's as an example i'm giving the this example which is a quite a.
interesting thing when you think about it because we have this problem and many of the bigger documentation sets but also in the smaller projects to something you can consider something we've been working on at had for the last few years is right now our star documentation tells us what every single button does but what our readers. as one to know is how to fly planes and k. so it's not going to matter with they know what every single control i mean it's this kind of genki every other to look nice and my laptop so i have to change the screen shot to something a little bit more modern right but everyone into software looks like this case so. you get all sorts but this is exactly the strategic thinking that why should i care what every single button does when i just want to know how to fly planes so goal oriented documentation is the key and then the next thing i want to know is who my readers are which is the same question is who is using my software so as an example i'm going to give the go home.
help which i've loved and they've been doing this really well for years this is where you get to the static talk site so if you type in help dot com dot org and then you get to their website they don't know who you are when you get to their website so the first question they ask us who are paying it worked for the caterpillar can work for these kids so depending on what you. you choose you get entirely different sets of documentation and case so persona based occupation is something that we're really trying to emphasize here. so you get the information you need and you don't get the information that you don't need so from a developer i don't really need to know how to use different things on the desktop for example and by the way the user's option is the same screen that you get a few quick f one in your bedroom desktop so in the right context it's ok. it to display directly the user's help because i know from clicking a fun in my desktop i probably have a question about something that i'm using right now but if i'm an administrator developer i don't really care.
and then the next question is what and what in the sense i mean what type of information and pay so depending on who your readers are ok and why they are already opening the documentation water goal are they trying to achieve it affects the type of information that you're going to give them so. for example if you want to. showcase different aspects of your tool or of your software you can give them fancy diagrams or architecture charts or if there are the coming into your read me for example and get have than you can assume that there are certain personas and then you can give them different types of information and for the example for that. will go to our humble reading and some of you already know i've heard great takoma name is reading my i found is very good so one of the things i really like this is a project that i used to be involved with red hat called many shift and it's a localized contain arise deployment of single not open ship. and we are small team and i was really lucky to be able to get this project docs on the ground floor and actually structured properly instead of coming in like a documentation mary poppins and just trying to clean up your help we clean up your house. so i use this as examples and i will use it on until they do something to it and i hope they don't. the reason i'm showing you this reading is because it's short time it's short and it acts like a portal to your open source project so if i have a good have read me that's the home page of my code repository it's also the home page of where i'm most. likely to get people who wants to contribute or people who are slightly more advanced than the average user who the is so if you have a static dioxide help that whatever dot org you know them that's where you get most of the common personas but year get hybrid me is a little bit more specialized than that and i get a lot of question. sounds about right knees and i say think about the read me like the foyer or the entrance to your house you do not want to have all of your crap there and pay because people can get really disorientated and a lot of times project start small and then they have just a few bits and pieces of information in the read me and. then as it gets bigger the read me gets longer and becomes a dumping ground for everything about the project at some point you're going to have to see how many times do i scrolled to get to the end of the reading a that's a good indication because if you do it more than a few times and you probably should split up your information so this region has everything has a table of contents it is written. ask a doctor but hubble render most market languages for you on the flight has a welcome has which projects we have used to fork this is a fork of munich you've been a shift in a cube net is how to get started we have already have documentation some smaller help topics on in. salacious and and configuration so has links there has links to the documentation and a very important part has the community section ok because a lot of times people get to your get have breed me wanting to contribute and this is what's going to help them get started and k. so la times are good questions how do i do. people from users to contributors welcome them show them how it's done ok show them how they can get in touch mailing lists you know if you have contribution guidelines for patches could patches and documentation patches. so next thing i want to ask is when when do i need to know this information let's talk about their message is it ok and trouble shooting information of error messages next day i just reach and read a little bit so that when means at which point the use. its cycle of the software am i going to encounter documentation so yeah error messages ok i will talk about them until the bell shown example later so when i see an error message sums broken ok and i'm not unhappy mood when things get broken so i need to know how much information. to deliver to my readers when they see an error message hint it's usually a little bit more than you think ok most is a time when i headed to error messages i need to expand them rather than compressed them so from my experience as a writer working with developers so house. so helps you figure out how to optimize the content delivery so for for the when i want to show the arch next week he argues ers can't see anything that's about the same and that's about similar where and when i asked in the conferences but i love this week he because they they love this weekend right and why do they love. this week because of this because it's optimized for impatient frustrated i have already tried everything users ok it doesn't need to look sexy you know it needs to work all the information is in there and you basically just search for whatever it is that you need to do so by the time i get to this piece of. imitation i have tried everything else and so i don't want to waste time on browsing help topics i know roughly the key words and so you can optimize your content delivery based on that.
last question i want to ask is where and where. i want talk about error messages again. so the where and when are connected obviously i'm because by the time i get to an error message i would like i said i'm frustrated but how much information do i give at each platform of delivery see can have a static dioxide you can have a read me you can have an error message you can have embedded help you. you have have or text you can have a lot of different ways of interacting can have many pages even dock strings in your a.p.i. which would hopefully get generated into some kind of a p i are friends there's a lot of automation around and already but how much information given were so you need to make the information excessive. people and. if you can write if you write the greatest documentation said ever but i can't find it doesn't exist i'm sorry you know so you have to make sure that people find this information so as an example one of the things that we worked on and many shift was there was a problem where if you install too many packages.
on the route file system of the many shift to be m. you can lock up the v.m. and it will just get to full the problem is we couldn't stop to the users from doing this kind and unfortunately from our experience a lot of times people will try to stretch the boundaries of the software you provide them the less you actually block them rights. so the proposed draft for this error message that you see in the terminal was installing additional package is not supported for more information see the documentation. there's a problem there are several problems with this air masses ok one is not supported in tech jargon means physically blocked cannot technically be done which is wrong because the users can install whatever they want on the route file system it's just going to cause them problems so first of a that's incorrect. the second is why is this not supported what is the problem that this is going to create and just sending them to a documentation link feels a little bit like a cop out you know it's like you can't do this and then go and copy vilain can put in your browser you know. so we're not giving them enough information that they can trust us not to do this thing that they're not supposed to do ok so why is this unsupported and what are the alternatives are the questions that we should ask and the answers are going to affect the error message that we eventually came up with was. in stunning additional packages on the route file system might exceed the l.a. allocated overlay size we can assume that they know what overlay size means and case of these are some patients about our users that we're making i did not know what overly size means but as soon as i figured out i was able to say ok so that works and it will lock them in the shift to be i'm so we have. of action. result cause the action cause result locking the militias v.m. proceed with the installation at your own risk which is something that linux users really like to hear. it's quite common right so i mean you don't have to be like very fluffier in your language so this is a relatively casual error message and then we give them the link in case they still don't believe us ok so if they really don't believe us we have helped topic. in the trouble shooting guide that actually describes in many more words basically the same thing that we said in the air message ok but as far is that start to give you the mountain s t n n like if people really want to be care about why is this technically a problem and cry but for most people this will be enough. ok and we do give them a link to the next thing to more information so where do i delivered the the information how much do i give you know why do i need to know this who needs to know this what do i need to know when to any to know it and where am i going to get this information this is based.
the cli content strategy which kind as you know it could sound like a big who knows anything with the word strategy and sounds kind of big but if you ask these questions it could be a matter of a five minute discussion that can help save you our is you know of a lot of documented in documentation work they might not even. we need to use anymore. ok so let's talk about the ups for docs i can't say dock ups because some company copyrighted and it's not even a devastating that they did and so processes tools and were close to my. the name of the game for us in the tech writing failed over the last five or ten years is definitely being integration because we all work together i am surrounded by extremely talented and very skilled engineers who make wonderful develops tools for themselves so i can use them you know why not. ok so there are some things here that if your active in the general community will already know but you'll get validation which is also nice so things that are being done right i will call out and if you find things that you are not still doing not yet doing then hopefully this will inspire you to do something. little bit different so doctors code as an example you have the documentation docs folder inside your get have repo which makes it easier when you submit code patches to also submit documentation patches of everything is stored in same place i get asked a lot whether documentation. in requires its own repository and i hate say this but it depends. it depends on how much code are you trying to manage how many code repositories do you have because if you have something with twelve code depositories and then they all get integrated into one big platform for looking at red had opened stack platform for example it's got like dozens of upstream. components that we pull in into a single platform that we package together and put and channel downstream into our customers ok there's no way that i can edit every single component in the upstream open stack repository and get a meaningful set of docs especially if we remember the goal oriented docs you know so. the all the action components for example in the open stacks foundation repositories are specifically in the components that they are relevant for but when we deliver a platform then we need to provide and to and use case scenarios how to deploy real time computer how to apply april. see and all of these different things require a different set of documentation so we have our own documentation repository for open sec platform at red hat but most of the time this will be enough for the smaller open source projects and the integration here is really really important and you can always move it out. but it's really hard to put it back in the. so hierarchical source content hopefully you have a similar thing in your code where you have some kind of folder structure and then things are grouped into folders you can do this here we have just topics because it's a relatively small documentation set but theoretically when your project gets bigger instead of having one topic for installation you can have a full. older ok and we try to make it so that the content topics the the topic chunks are small enough that you can move them around and you can reuse them so i believe and scroll free as much as possible and venue will be able to have the source file structure. mirroring your published documentation set hopefully the other thing in this is something the gender does right is having an integration of dr dock bugs interior issue tracking. that part is done right. the issue tracking itself might use a bit of work but that has nothing to do with the documentation we are but i mean all issue tracking platforms. have their of sudden downsize so having a documentation component means you can flag issues as documentation issues and then you can also marked them as tasks as bugs you know that's the usual thing that you would do for any kind of coding task so if you integrate this it also helps people feel like you know. if you have a writer who wants to contribute it feels like they're doing something a little bit more meaningful if you're giving them you know the ability to say this is documentation issue at the same level of respect that another that a code a technical code issue would have. surges bringing them into the family you know makes them feel welcome. so continues publication i remember when we may dock cities there was a nightmare we don't have to do this anymore you don't have to do this anymore with most of your software i mean i don't know who have been anybody still writing code for something gets published on a d.v.d. and not also online.
and right. to create the end it's less wasteful. so. continuous publication there are lots of really easy ways to do this if you're in python you can use thinks and read the docks ask a doctor and ask the doc for ruby have make docs have get book you have a lot of different parts ers a lot of them are available out of the bucks you know even if you have a small project you can even you just check a checkbox and get help.
wages will publish or docs it for you you know so there's a lot of different low effort ways that you can do a single establishing you can i put stuff into your bill sequence you know every time you know you can release you can also cut their lease on the documentation the conversion you can french did all kinds of great things.
else could have like previews of your documentation site right ducks we use notify and we have a lot of different now get this again.
and. the.
i know stillman wrong way. k..
worse ago and so what i talk about i talked about this yes so testing our nation is still hard for documentation because unlike code prose is harder to compile neatly into binaries so a lot of the tools out there are more.
named for uncovering problems rather than once a fixing them for you and it's a lot trickier when you're talking about you know linguistic grammar and syntax so i would be happy to hear if anybody is working on cool things especially there are solutions for things like that but not so many open source ones ok so i'm on. we talking about open source of here and so for example literally last week found out that one of my good friends from katie project they built a tool that aims to do just one job which is testing called blocks in march down files and pay you can run it locally you can run it in you can put in your build sequence.
and it basically runs code blocks from mark down files in a shelf uk so which shalit is depends on your system and adjust validates that whatever you have in your coat blocks works now i know for restructure text and ask the doc in the more robust market languages there are tools for this year's dr esther's you can dynamically in bed. roadblocks in your topics but a lot of projects so use mark down right so this is a quick and easy way to do this and people can extended and its open source and you can look at it later. the next one is of course the trustee hemingway app which will help you if you feed if you copy and paste text into it they can highlight some things that are a little bit flowery and probably not so concise unfortunately it only works it works best in smaller chunks of taxi probably don't. when a fee to five hundred page manual into it. but this is an example of the things that it can do right so if you want to get more robust this is where things get a little bit harder so this is a test automation framework for documentation for english or translated pros there are open not open source oceans for this which i'm not going to mention but this is a tool that. but my colleagues had condemned services are working on its streets open source and it's called him and are and you basically feed your style get into it and feed your grammatical conventions to it and the of course he will be faced with the question how much to invest in test automation versus how much value i get out of it. that's something that you're already dealing with these questions when your coding so this is another thing that you can consider. the. the last thing i want to talk about before i get to the questions part is the community spirit so when i joined when i moved from israel now i live in prague and when i started traveling around especially python engine go and then write the docks i realize that there's a lot of things that we can do when we. great and one of the great things about working in open source is that there's a lot of that spirit of collaboration and i mean i'm i'm drunk the koolaid i'm all in it and it's really really wonderful and i am happy that i get to come here and talk to a lot of people from different roles and there's a lot of things that we can do to. be more welcoming to contributors and two more users whether it's from documentation our code or whatever it is to our project and case it's not just about the code it's not just about developers it's about the sorry the community ok so. doc certain happened repeat after me doctor didn't happen so let's try this again dr turn up in it. thank you very much this is not just have. this doesn't work at every conference. this is why i like this community k. documentation as a deliverable as a requirement doctor didn't happen is not just of a funky tagline it means give me docs or i'm not accepting your patch and k. chamber project does as linux kernel open sack a lot of different project do this and i mean yes you should. actually enforce this obviously but having it documented on your contribution guidelines is a good start because you're saying this is an official thing this is a policy ok you make documentation contributions into your code contribution policies a step number one and now. but you've made it into your policy how or he how are you going to help people learn how to contribute so you write contribution guidelines and pay and and give them help google docs the docks you know so how to dr ducks something with it for nick so as a few years ago there's a lot of different projects to have this kind of thing. and i will talk about this in a second. and so of course you want to give them also templates write code templates you know a lot of people copying tastings and why not have this for your documentation is well this is a relatively this is on the right the docks website and i'm pretty sure we've gotten the most hits is on this page ok the read me template. and so whether you're just doing a small read me over the doing a much bigger doc said. then templates are great there are many out there are one of the latest things that i've come across is something we're doing and have which is called the modular docs project so if you're looking at i mean this is a very small read me it's very cute but if you want to do. documentation plan ok or few and actually build a strategy for something that will scale uk it's worth checking out this project because it gives you we have a reference guide where you can read all about we know what is modular documentation and when i say modular documentation i mean small. content chunks that are reusable movable and you can assemble them in different ways the terminology is actually not the most critical part year you can call the modules you can call them topics it doesn't matter the point is this is a free and open source project that we encourage communities to use and pay and you can understand things like you. no and this is based on the topic based architecture which breaks down topics into concept task reference which is fairly standard in the tech writing world but what i like about this is we have templates and cases there are templates here for any kind of for the most part of the most. some documentation types that you will need and if you this is a just a route put of the procedure template so this is a module and it tells you you know it gives you suggestions for naming conventions and it also gives the things like you know start each step with an active verb and all. all sorts of things like that include one command so it gives you best practices and how to write a task topic and i know something people still struggle with this because it's not a lot of engineers a lot of people who are not writers you know just like people have developed a skill set in writing code you know i have developed a skill set inviting docs you know. and it's not something you know a lot of people ask me you know how do i write documentation if i'm not going to change careers now and you don't have to do this because we put out some best practices thankfully and some templates these resources are available and then last thing i want to talk about before i get into the questions is. i said we are surrounded by humans we work with humans whether it's remotely or in person and the personal connections and the social aspect of working in open source community is much more felt. when you're talking about documentation. because it's all about communication right so i want to talk about right the docks because it's one of the happiest communities that i have been very fortunate to be a part of we have this year we have five conferences we've been around for six years i joined in five years ago we have conferences in portland and in practice. is our main conferences and we have new conference as well as trail years in the third year are ready we have cincinnati last year collaboration with open help and we have a new one this year in vilnius in june and this is the place where you go and learn about you know way more things and i talk to. but today like this this presentation is kind of a hopefully to inspire you to think a little bit differently but also to tease you to want to learn more about this about the documentation world about content about collaboration and pay about communication so this is my home and. i'm really happy to be there and the other thing that i do is come to these conferences have done this in the past agenda under the hood and i've been running documentation sprints so you know next time you go to any kind of python django or any kind of open source event you know know that writers walk.
among you and we are here and we might not be the majority at these events but we do try to get to a wider range of open source and technical events to be able to collaborate so i'm not just inviting you to come to my home at right the docks and also telling you. that we are among you and it's probably good if your next to us because we might some docks for iraq. can i do want to give a shout out for season of docs few no summer of code then it's like this but for docks and they're doing it this year for the first time the application period is open now an open source projects can apply and then you can get writers for free to do things for you and you get paid and the writers can you.
paid and it's like a mentorship minutes and they can you can help you can get help for open source projects the would not have otherwise gotten in the documentation area so google's google season of docs is a cool thing that they're doing now. ok we're good writes i have time or minutes i want to start with a few questions that i got in advance and k i have been tweeting like hell in the last couple weeks asking for some questions and i have crowd crowd sourced anonymised and.
none weaponized questions i do not accept weaponized questions we may not have time for the microphone stuff ok but the online things could happen hopefully they're known weaponized as well. if you ask me weaponize question you better be prepared to deal with the answer. this is why don't they questioned. ok so the first question is about in a has to do with grammar syntax and linguistics and the question was do you see benefits in using or avoiding pronouns and docks and then later we've kind of elaborate are clarified that it's also a matter of of journeys and infinitives property x. allows you to do why. versus property exiles for doing why do you have any recommendations on when which version makes more sense or it's more appropriate so there's a lot of few examples that we were waiting on twitter until i understood what the question was but the answer to all of that is minimalism and pay which means use fewer words. one of the things one of the first things that i was taught when i became a technical writer is you have to keep it really really simple and k. and even more simple than you think and and not as in the topics that we write about are so complicated sometimes that the language has to be extremely simple. so these are things that for example surfer looking at the examples that the question was listing so property excellent as to why property x. allows for doing why with x. one can do why with x. doing why is possible with x. it's possible to do why. you do why with acts carried acts with whiteside because the x. comes first so why am i flipping all of this into you do x. with why this is a minimalist approach and pay and even if a before he was called minimalism you can google. him as a right so you second voice i have not had a second voice you in the relevant context ok so you are addressing the user or the reader directly ok this is what we try to do as persona based documentation so you're not saying you know. ministers can do that we want to make sure that we are addressing the user directly as much as possible uk. in the second reasoning for this is that things cannot allow humans to do things it's the same way it's and and travel more fearsome i think i'm producing right it's a really long word but it's basically giving human attributes to inanimate objects and i see this happen a lot of the other so. things like a software tool cannot allow you to do something you use the tool to do something ok so we flipped the way we think about it and its action based goal based user based the other. side engines have very few side tensions in this presentation of quite proud of myself things cannot have things ok this tool cannot have. attributes it includes it can describe it does things. software cannot own possessions also have is a really dangerous word anywhere active ice indicates the goal first and the method second so for looking at goal oriented wording and then jan's which is anything and with i enjoyed doing streaming browsing writing are dramatically ambiguous and hard to. and sometimes so if you have. probably sometimes if it's in the middle of the sentence it could have different ways to slice the sentence. but generally using journeys is best avoided in regular sentences so unless you have a title for example that says installing this to ok adjourned is fine because it indicates a continuous action and it's not ambiguous and casey have to use geron very carefully. so that was the linguistic question that i got the neck the second theme i got a few questions are actually related. and i'm going to have there's a lot of texture. so i got a project i know any docs i can write but i know it's not my strength what do i need to do to make it easier for someone who does have the skills to contribute when starting a project from scratch how does one figure out how to structure the documentation in water the first and things one should take care of it's very hard for someone to write documentation for project if they don't. you know how the project works how do you best facilitate that knowledge transfer other than of course writing docs how do you bootstrap the process i don't know what i don't know so how can i possibly know what you don't know. that's a really good question and i have to say not everybody has enough awareness even asked this question ok so i thank you for all these questions and they are all related because the answer is you have to talk to people with a sorry you know.
a. but i talk to people all day this is my job i understand that it's not everyone's job to talk to people all day but this is something that would be the easiest it the easiest way to solve things would be to talk to people so if i take the first question you know how do i get people who might have. imitation skills to contribute to the project so here's a few tips ok find people with writing experience as and you know i said we walk among as you or you can do some calls to action you find people with writing experience and or who are interested in it asked him to test your software ok and. then figure out what kind of work flow they're using asked him to give you feedback and then hill and then help you build contributions and pay another thing that i think is great katie project does this mean i don't know how many other projects are doing and i just recently learned about it is that if you have a. easy pickings or junior jobs flag in your issue tracker they attach a mentorship to this so it's not enough to say that something is easy right as easy as a subjective thing please remember this was easy for you might not be for someone else especially if their new so attaching a mentorship two. the easy pickings issues can help bring people in to your project so it could help it can bring a new contributors you can fix your doctor might not necessarily have programming experience of or even have experience with your project you know my my favorites my least favorite admission is self. documented code is code that you wrote recently and. so i mean even if our site read had most of our users are developers but they didn't write the stuff that they're using you know this is another perspective you can put in and the other things you can use you can facilitate skill sharing sprints so for example if you invite writers to your developer sprint and then you do some kind of pair hacking. or you know some kind of collaboration and where let's say from writer i can learn more about your project and then i can help you contributed to this reply be i did this work with a lot of different projects and i think it was it was quite well because and you can take what you learn and you can implement later so the second question for that was when. how to structure the documentation ok so there's a couple of things you can do first of all i already talked about things like templates and the modular docs project and figure out how to store your content to scale but you gotta ask quote unquote potential users how their work for. so how do they actually use your tool ok and then from that. common set of tasks that people want to achieve with their tool this is you can port that back to your documentation so in a similar way that and bigger enterprise projects we collaborate with the queue a testing teams so they built test plans and then we use we leverage that to make documentation so it's a similar thing whatever you. testing more than unit testament talking and to and testing and then you can also research best practices and templates there are more resources out there for that. and then he's just two questions are basically the same i love as i don't know what i don't know so how can i possibly know what you don't know and that is a great question and accepting that you have a problem is the first step in solving that problem so just by and admitting ok. and understanding that different people have different starting points in their knowledge and just because they don't know what you already know that doesn't mean they don't know anything and so they might know different things so reach out to your peers make yourself available for. training and for mentorship and be kind to the people who want to contribute because welcoming project gets more contributors ok and that is something that i've seen a lot of different places and this is part of why i'm still involved in django and python communities. because you have been extremely well coming to may even though i do not write code all ok and you've you embrace the different skill sets that are needed to create better software in an open source way and this is why i'm still here so if you want to be bring more people into your projects be nice to them. i know. so in the last thing i want to say is most or a good percentage of technical writers or documentation oriented people such as myself and many peers that i have were extremely talented writers we do not have a deeper understanding of how your code is written and pay but the strategic communication and the ability. to see things on the bigger picture can help your project so you you should respect that and you should embrace that in a collaborative way and we have i think maybe a few more minutes from are questions what's happening on slack.
time is up to what can we take like where is ok do we have like a non weaponize question from slack and that so i will just say that if people ask questions on slack i will read it later and i will answer them personally letters so if we don't get to it now i will answer this question about having much time. and if you have to suffer project that doesn't have any dogs and you have little time where you start was the single most important thing to a to document or to ride reading using read me you can base it on the template for might the docks or something like that and you have just enough information it could be impaired. half a cake take you like a couple hours just to understand what the basics of the project is just start with a rating occurred during the other questions or was live to be answered on slick lovely you're probably probably ok that's the axe.
Feedback