 Yeah, hello everybody, I guess some of you may know me or may have written May have read stuff I wrote and I think only few of you have seen me actually talking about this topic which is very important to me and this is actually Something I created based on my experiences at Zuse linux distributor and This talk is called myth-busting documentation. I thought this is very very important because there's so many myths about documentation around and This is what I'm going to talk about Nothing is written in stone as you can see here and I I try to Yeah, I try to have this in a little bit funny way even though it is a very serious topic and there has been Yeah, somewhat heated discussions over the last ten years that I was to witness about the different approaches to documentation and You can just lay back and feel fine But in the end this is this is what we're going to talk about today I'm gonna introduce myself shortly then I'll show you some common myths about documentation and Tell you what the perfect writer looks like because we all as you will see we all need documentation writers Then I'm going to destroy the myths one by one and have a short some some short words on Automation and agile documentation like an outlook into the future so Who am I? Well, I'm a journalist as you can see and I was Happy just two days ago to visit the press freedom award. So this is the most recent selfie I found I guess it's yeah, it looks like me. I Was for eight years. I was deputy editor in chief of the Linux magazine in Germany an IT consultant and writer before that and Then for five years. I was the team lead of documentation at Susie and I Now am since May I am again in journalism as senior managing editor at Heise in Germany here big Publishing house and they are producing the IX which is the magazine for the professional users. So everything that is Professional and doesn't need to be fixed every other day. So everything that is supposed to run and work There is documentation all around the world everywhere and there's a lot of common myths about it And I really like this kind of documentation here. Is this a very very old? painting writing, I think it's some centuries old and some of you may know where it comes from But anyhow, let's start with the myths one of the biggest myths is That I heard a lot from both developers and managers in development. No one reads the documentation So as I told you I'm gonna present the myths and later. I'm gonna debunk I will debunk them Good code does not need documentation Everybody can write documentation. How often have you heard that? I guess I don't know how many of you are in in Say bigger or medium-sized companies So if you are in in corporate IT, this is probably an even bigger topic because much to my experience Smaller companies who are more in direct contact with customers They do not they are not that prone to these Myths then everybody everybody of you everybody wants to write documentation, of course and There's experts for documentation everywhere. You find them all around the world Everybody wants to everybody can and it's not a tech job at all Writing is not a tech job How can it be and this was the worst thing that I ever heard it was that is why gender equality is much easier there I will come to that later Then there is one thing I was really surprised to hear was that why should we document? Obscurity is good for our business if the people don't know what we are writing about They will buy our products in our consulting and our support Then there's people who are Only happy if they have their own tools if they don't have to worry about other things And if they can't just stick to what they've always done and no matter what and There is the concept of heisen doku and heisenberg documentation or heisen doku as we used to call it That's where people especially developers say that the documentation people. They are so locked in into their world They love their tools. They invest only time into Making their tools better, but at the same time it's totally old and obsolete because those documentations they are like the librarians of software and Everything they do is just complex and that a tool chain that doesn't make sense and then and so this is These are the myths that I will go that I will debunk in a few minutes Let's have a look at what is the perfect documentation writer? What does he look like and? I found with working with at the end 16 Wonderful people at Suze a wonderful documentation writer some of them with more than 20 or 25 years of experience I found out that these people have a long long list of Qualifications that are necessary to do a good job in documentation and you will have a long list here These people need a good writer needs or the perfect writer needs technical skills So at a level that he could be an administrator at a customer He needs to know the software he's writing about as well as his target audience after reading that He needs to have development skills to understand and follow the developers and Their teams so he needs to understand what the developer actually does what they changes are or what this source code comment might mean That's why he needs coding skills to understand the missing source code comment or to understand what's missing in the source code then we have language skills and Of course because he's supposed to write and he should be an expert in grammar Then he should have emotional intelligence to do the mind switch from developer to user To understand both what the coder meant and what the user wants because this is often not really the same and of It's was it to me no then and then there's project management skills because he needs to prioritize he needs to find out what is important what is not important and Accomplish the needs communicated by product product management And of course the ability to understand and improve documentation tools and workflows. Oh And profound understanding of marketing sales support and consultants needs. So it's an easy job Obviously here the perfect writer. It's it's Only the geeks only the good ones here But that's not all Because you also need understanding of legal trademarks licenses up and downstream corporate identity and styles in language and and layout and That is a set that I Really do not think that most of developers or development teams Actually can have in their vision because it's such a big and huge amount of stuff Especially when it comes to licenses, what can we include in our documentation? What can we not include even with open source licenses? There is stuff that you simply cannot include like pictures or whatever Even if they are CC license, you may not be able to include them in your documentation license because your documentation license has It has different paragraphs that diverge from that and that's stuff that you don't want to deal with and Also automated checks in documentation. I will talk about that later a little bit Then the different kinds of media which have different Styles and different needs Lots of customers really still want printed books or printed documentation then You also need to understand the difference between stable versions or emerging products like we had at Susie Susie created a lot of container products in the last years and these products were sort of written from scratch And so was the documentation that is something completely different than just taking care just in inverted commas taking care of stable version documentation which is continuously updated and You need to set to be able to set up working setups for testing of Software that doesn't even work right because it's alpha software and You have to be able to retrieve the information from the developers which in my team. I was reported was about Something like 70% of the time was running after the developers and getting them to explain stuff and to show stuff to them And this is the the slides are on the websites the slides will be published So you don't need to read everything here This is more than I am able to say in this short time that I have but the top 20 replies of programmers When were exactly that and my favorite is also number one because this is the best thing you can say in times of containers Short form for containers anywhere is it works on my machine Tools for documentation to get the information we need from the developers. Of course, there is the phone bat The whip that we created for ourselves, but the most Successful tools were like this little hook on the left to drag the things out of the nose of the developers because they are not really not always that communicative or of course the crystal sphere the crystal ball To just guess the stuff but nevertheless the developers would act react in their own way They would they're just new it's some of the I've seen some of the most skilled people I ever have met at Susie here, but they just they just follow down their track and yeah, they have things to do and Sometimes you have to drag them Somewhere you just have to get them get hold of them drag them somewhere even against their will and to pin them down to Tell you what you need and for that We had to install quite some Were ways of working with them with development We invented for example, we had dedicated writers or engineering writers The difference between the two is engineering writers were inside the engineering teams They were immersed in the development team in the group of the developers So they were very close and always knew what was going on They were in their sprints in their meetings and everything where it's dedicated writers were in our team But dedicated to one software project. They were little they were integrated in our team, but close to the project to If pending on the workflow of the development team Either one solution was better Then we invented continuous documentation and sort of like to cope with the agile methods of some teams and One thing that I was really driving forward very much to get as much input as possible was format and tool agnostic input So just give us text. I don't care. I don't care Give it give it let it be word document office document plain text email Markdown wiki ASCII doc whatever we don't care and you should not care if you are developer you should not care Just get us the content. We are the specialists for the rest that was one thing that was very important for me and This approach also helped a lot in in the face of flame wars about formats and Like ASCII doc versus dog book xmo versus sphinx or whatever Frameworks there are if you just tell people I don't care. That's your thing. You do it like you would want we can we can work with that that all includes a lot of meetings and As I said, we were working with sprints squads lots of agile methods and flexibility the core input to documentation and That may be Debatable for you, but that's my findings should come from product management It should not come from development because Development usually is not in contact with the target group not directly in contact with the user, but product management They are the central information hub and goal setter for everybody they are the guys who have to say no So they have the money they have the budget they can tell okay We have to document this otherwise we will not sell this product or they will say no We don't need to document this because we'll sell the product anyway So it is their decision at least in a bigger company like Susie it was and this is where the priorities are set This is a where we created documentation plans with them We discussed what needs to be documented and that would be like the plan for the next year for us How we do documentation and this is also where the plan is jettisoned And I tell you writers better do what the project product management wants It's not a good thing if writers do what a single developer wants How no matter how creative and how wonderful the new thing is that he has integrated here Documentation is one of the pillars of success of open-source software for the customers and the customers are in the center So at Susan and other big companies you have like Yeah, you have several entities several people several group of people who are there are directly working with the customers That is the sales and sales engineers consultants even marketing in PR Then you have support partners every customer himself sometimes they you they started directly contacting us and Every colleague out in the field knows what the customer wants and these should be the ones that have an impact on So listen to your customers when you're doing documentation is very very important and Back to the myths So these were my learnings from Susie and back to the myths and I'm going to debunk one by one. No one reads the documentation well It's the opposite the people who work with the customers the ones I just mentioned they tell us they actually read it they need it and interesting for me was there's especially in in the Asia Pacific region There were a high amount of customers who really would print out documentation or asked customers for a printed book Version of the documentation, so that was surprising for me too in times like today, but still Then good code does not need documentation something I heard very often from developers or also from management of development and It's it's not true because Especially for open-source documentation is one of the pillars of success for open-source companies other Many software tools only become usable thanks to detailed Documentations and if you are in a company if you work in an IT department and if you are responsible for working for functioning software or Environment and smooth processes This will affect your daily work and even the success of your business Just imagine you have this one colleague who is the only one who knows something about one workflow Then he's got a car accident. He's in or whatever is it as we used to say he's eaten by a bear and Then you have to you have to train somebody on this It is for many companies. It is like an insurance if they know we have a book and after three days This one person this apprentice or whatever is at a level that he can do the basic stuff there This book is like an insurance to them and that is why it's important for them they really want to have this in a shelf or as a PDF or whatever and Get somebody ramp up somebody on board somebody on a task and replace somebody. This is an insurance for them we heard that so often and Yeah, that's what I said. It's a Appreciate in terms of faster onboarding also we documented our own documentation workflow and that worked quite well with onboarding people very well. Oh Yeah, if you have questions just interrupt me, but I'm sure there will be some time after my talk for questions The Marines wouldn't be the Marines if everybody could get in there, so I'm not thinking of the documentations Community or people as Marines, but If everybody can write documentation, I wonder why there is university degrees on Technical documentation, so if it's that easy I why do so many people at universities waste their time on that Then why does it take months of onboarding to integrate a writer even good ones? Yeah, because you need to learn a lot about the company about the environment about the customers and all of the stuff that I said before and then there is Stuff that is in the character in the mindset of documentation people that are also addressed already and I'm addressing later a little bit more about bias and problems of assumed obviousness that means they have to have the emotional intelligence To do the mind swap to to understand what is not Self-understood for somebody who sees the software for the first time And you have to keep to have an overview over what you're doing Otherwise you will end up in situations that you don't think that might be possible So obviously here was somebody who didn't know anything about encoding This is on a train a photo. I took on the train. I think it was in Belgium if I'm and this is there's a lot of skills and Even though lots of developers want to write documentations And even though they love and care and know what they do They are not in not all of them. Let's put it Carefully not all of them are the best people you would want to write Documentations there's a part of part of that is because they have a different view on the software. They're developing. They're an insider but I heard that from several sides from consulting and from at conferences that the Developer is the probably the best informed person He's probably the least desired one to write the documentation just because he's too much inside and Yes, I know we I heard this from a consultant who really told me even though we don't have documentation for that Don't let these two three people write it. They won't this will not succeed So every yes, there's there's probably more people who want to write documentation then there are people who are able to write proper documentation that is helpful for customers and That's again because of the problems that I said that I mentioned before For example, these people often are not involved with legal matter with legal Questions like maybe use this text. Some of them would just copy Online stuff from other software projects thinking this is open source everything and put it into Enterprise documentation, which is part of a sold project and then you run into license problems. So This is stuff that the documentation experts know and I said before Remember the perfect writer. There is a lot of skills That is needed and that is why it's simply wrong to say there is documentation experts everywhere. That's wrong There is not many it's and that is leads us directly to the wonderful statement one of my friends and colleagues former colleagues said when I told him that I was successful in raising the the the share of Women in my team from one to seven sort of like from five to one to eight to seven So almost fifty-fifty when I left the team and was very proud of that And but the the comment that I heard was well, it's so much easier in documentation It's obvious that it's so much easier there because Documentation isn't a tech job isn't technical and I had to I had to breathe in air And I said are you aware of how many discriminating statements this sentence contains? Yeah, so it it's if you count them I came to four or five groups that he just discriminated with this one sentence He thought about it and just few weeks ago. He still said yeah, that was stupid That was very stupid then but it's just something that is in the mind of people and that's just wrong because also in IT Well, there's many theories why women are still underrepresented in IT But it wasn't always like that and for those of you who have seen the movie about the moonshot the Apollo program Or who are Who are a little bit aware of world war two cryptography and early IT after world war two They know that women had a very strong role then much stronger than the men at the time This group of women that you see here is the women from Bletchley Park. They broke the they broke the enigma They broke the order broke the German cryptography then yeah, then any act such just these look up these these Such any act at Google and stuff any act was one of the first bigger computers after World War two and it was almost only ladies Working with it entering the data into this computer any act was used to calculate trajectories, I think it's the English word for for not bombs for rockets Yeah, so the Where how do we how which angle do we need so that it hits there and there yeah And there is one statement of one of the leaders of the one of the leading ladies of this any act project who said that Finally, we have reached a point where the the calculation is faster than the rocket and Hidden figures was the movie I was referring to about the Apollo program about lots of the ladies who did the The calculations and stuff and there's a wonderful picture of Margaret Hamilton if you remember that I don't know if you know that but if you Google for her name and and you will find it She's standing there. She's a lady. Maybe that tall and she's standing there beside her is a pile of paper and That is the printed software That is the printed code of the software of the Apollo program program It's as tall as she is and she was the team lead of the program then so up to the 60s It was much more standard that women were in IT in fact computers was a term that was Describing female Data scientists we would say today or female Workers at a computer. It was associated with a female person a computer was a lady then so and No, I I don't agree with this friend of mine. So if you like to do some research It's really interesting somewhere in the way in the last decades. We have lost that a little bit But hopefully we are getting there again now so the one of the last myths to debunk is Obscurity I heard that when I was talking to another open-source company a big one and Somebody asked me how do you at Susie decide? What not to document? And I'm like what and then this person explained Yeah, there is stuff that you want your support to make money with right And I'm like what and he said yeah There's really stuff that we do not document because we want our our Support to have a lot of tickets from the customers to make money with it. I'm like, okay This is not open source at all and that's Obscurity doesn't help you there at all because there's three pillars for success of an open-source company That is consulting support and documentation within consulting and support. You also have the packaging topic of giving Updated security patched packages to people updated with new features and then and but you have services and support Means they you get you give them help when they need it you give them you guarantee help Yeah, and documentation and of course I don't need to say that hiding that this hiding information manager mentalities against our all open-source business and One thing that's also not that new is that we have a different situation of first-class Contact with customers our customers when they come in contact with open-source products They inform themselves ahead of buying when in former times marketing was the first contact with a customer And they would come in and hand in their brochures and their PDFs and whatever Today they meet customers that are already well informed and if these customers don't find the relevant information in type of documentation or Similar they just turn away and go to your competitor because the code can be used by somebody else And if they have the documentation, they will think the customer the potential customer will think well This other company probably has no clue about that Huh, and they will take the software from those that have a clue if there are So the heisen doku oops already said that it's it's about tool centric or the myth that documentation people are always worried tool centered and that is in my opinion that is wrong because Documentation needs a lot of tools, but it's much so much more than only the tools We did a lot of automated stuff in the background. We did style language texts We did we tested on logical consistency legal and licensed topics and a lot of other stuff in the background And we at least it's usually there were like 20. Yeah, there were 20 years of experience in choosing the tools that were most suitable for that And that is for example something that directly leads you to why are you using XML? Because we have a lot of machinery in the background that is working with that and that XML of course XML was made for you not made for not made readable for humans But for machines and it has many advantages of checking and stuff to other languages just for an example so And Customers of course make a big difference No companies think of making a difference between Marketing and documentation stuff, but for customers Everything that is tech or has tech is tech related will be considered documentation The customer doesn't care where it comes from If it is a white paper that was written by by by marketing or if it is a chapter in documentation the customer will take it as documentation and That is also one thing that documentation knows because we Talk to the marketing people. We are in contact with them And that is also something that developers rarely are or will be two minutes. That's good so I'm already almost done. I'm short. I will shortly talk about the future and about optimization and agile stuff that we were very much Concerned with What I don't know. What do you think about automating documentation? language I am Yeah, I see development, but I am not that Convinced yet because I think the source code of documentation is language and language is not standardized and or formalized There have been approaches look it up in airplane technology for airplane Documentation STE is a simplified technical English language and there have been lots of attempts, but so far I haven't seen reliable and working automated documentation That is because documentation is not standardized Other than code other than the code that you are working with that is standardized and that code usually always is Clear and precise language is not like you see here put file a in directory B and rename it It is it depends on the context and you need to have prior knowledge to all of that to know Whether you shall rename the directory or the file and there's lots of examples like that My former colleague Tanya did a whole talk about issues like that addressing them to developers Because Here we have assumed obviousness is if you've done this 20 times you just know that it's the directory you need to remain rename Huh, but if you've never done it before you don't know and that is assumed obvious and that is why developers are the last the least Wanted to write the documentation I've said the other things before Another thing is terminology Just I just pick one example. You need to pick them in terminology thoroughly We have that also at Susie we have a whole list We have libraries of that and that is what documentation people work with and that is what marketing works with they have an impact on it That is what developers never know and they don't need to know and For example, we have the you have the peak of mantis shrimp That is not a peak of not a mantis and not a shrimp, but it's called like that for whatever reasons Agile These are the best advice because I'm almost running out of time. These are the best advice I could find on agile documentation. It is a really an interesting topic and There is a lot of discussion on it This these are the things that we found out to be working here We have to think and plan and work iteratively like agile like the agile manifesto says We are with also part of this talk is going more into the user realm into asking the user finding out what they want and Analyze it treat it as a product towards best for the customer Create and support a writing process that enables contributions from outside Automation also here and there is also the CMS that comes in There's a very good link about technical writing and agility and this is the last slide This is what hopefully is the outcome if you have more agile documentation Honestly, I've never seen that working, but there is I've seen a lot of agile development working But I've also seen a lot of agile development not working So I would love if you are in a company that has this working Then let me know the graphics is very simple You see classic documentation is the red line You have a lot of work at the beginning yeah, and a lot of work generally over all of the time and with the agile Documentation you have to do the documentation much later, but it will be much less work. That is the promise. I Have never seen that in process So if if you see that then let me know So this is the end