OpenDOC: Automating Documentation
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.
Feilner, Markus
Heigl, Richard
A suggestion for a new approach to documenation. "Breaking the perception that a rolling release cannot be documented" Forums, mailing lists, wikis, release notes, Git commit comments, QA tools like Open QA and many more: A vast abundance of resources offer indicators for documentation. However the data is neither collected nor structured nor viewed at all, mostly because everybody thinks it's a tedious work. But modern knowledge management tools can collect the data, structure it, add semantic analysis and put it into a format that a community can benefit from - with minimal human input. Imagine a website like Stackoverflow or Reddit, but (open source and company-independent) with automated input, but ranked by interest (views), helpfulness and discussion thread length. The input triggers could become an open project, like Open QA's tests. A "Doc Gardener" could then pick up the most important tasks and move them to openSUSE wiki or Enterprise Documentation, at the same time helping the community and spotting pain points of the community.
 So, hello everybody and welcome here in this audience and thank you for coming as so many people and hi to all the millions and billions in the different variety of the Internet's out there. I'm Marcus Farner. I'm happy to have you here. Thank you. Thank you. Oh, that's it. That's all I wanted. Goodbye. No. I'm here to present an idea and I am fully aware that this, that I am presenting here is the produce of a lot of talking, quite some beer were involved in fact and quite some ideas are involved and it is, it is nothing that is finished of course. It's just an idea and I am here because we want to hear from you, the open Susie community, what you think about it and if you think this is possible and we are basically we are trying to make something impossible. It's about automating documentation which is impossible and you will see that. Well, I'm here. I'm Marcus Farner. Some of you may know me, I guess. And with me is, I'll tell you about me. With me is Richard Heigl from Hello World. Richard Heigl is an expert in knowledge management and in the course of this talk I will tell you why he is here. I am team leader at Susie for documentation and I am absolutely impartial. I was an open source journalist and that's why I am absolutely neutral. Some people say I am a Linux expert. I wouldn't say no, I'm not. I would say no, I'm not. I have been working with Linux since 1994 and I have quite some other maybe interesting stories to tell. I am a conch diplomat, I'm a priest. I'm a Jedi knight, I'm Encelado citizen number four and I own some property on the moon. And my boss says I'm running through the worst. So that's what I hear from one of my colleagues recently. If you want to know more details about either one of these things, just talk to me and ask me about it. And for the non-German speakers, if you feel any emotions involved with this talk, which I think will be inevitable, just get some hugs for that. So I want this thing, as I said, it's something for discussion. I want to hear, we want to hear what you think about it. All of these next sentences will be, I guess, maybe controversial, more or less. I think open source communities do not write documentation. You can always contradict me, prove the opposite. You think they do? I think, do you think I'm right? Thank you, Jürgen. Next one. Developers want to write code, not documentation. I just said this several. Every open source project needs documentation. And documentation cannot be automated. There's always humans who have to write documentation in the end. Though good software should not need documentation, it should be self-explanatory, proper documentation, resources are essential to attract new users. It's mostly the newbies or the ones who are new to something who need documentation. Tumbleweed is a rolling release. No, yes, it is. And it's moving way too fast to be properly documented. Nobody disagrees? Good. Seems like I did my homework at least a little. Nevertheless, there's a lot of data. We have a lot of information that we are gathering. We have data in this open source of Wiki. We have data in the mailing lists where people discuss solutions and discuss about good or bad solutions to problems. We have stuff even in the build service. The build service has a lot of information about version numbers and more. We have information in forums and release notes and get comments. And there's the documentation that we, the SUSE documentation team, provide. We develop new forms of documentation like the SUSE best practices. So, sort of like modern style how-tos for achieving single tasks with SUSE products. So there's a lot of documentation. And that's not all. That's just what I just, this was the point that out here. It's just a little bit, a little tiny bit of the documentation that is around in open SUSE. And in SUSE, and there's even more with some other projects somewhere out there, anywhere, there's still even more stuff somewhere in other forums outside. So, what? This picture is hanging over here. I thought it was in the other room, so I put this picture here. It says, this ball painting, it says, if what you say is true, the Shaolin and Kogan could be dangerous. And I think this is pretty much what's happening here. We have some, we have five facts and I think it's, there is a solution, there may be a solution to it. Community and documentation are difficult couple. Oops. Wrong. What is it? Jump over. We have a lot of information in a lot of places. I took this picture last week on a longer holiday trip to northern Germany. It's a beautiful beach. It's called the Amber Beach. And if you dig a little bit, on the beach, you'll find quite some worthy stones, some gems. And it's, and that's what it's all about. It's about finding and presenting it. We have lots of information, but we fail in finding and presenting it. And I, and now we come to the last one. The last fact, or the one before last fact, Tumbleweed is changing faster than anybody can document. Oh, really, I don't believe that. We can do better because nothing is written in stone. That's why I want to introduce the idea of OpenDoc. OpenDoc is just the name that I thought about for this project because I think it just fits. And it's sort of, for those, for those among you who know about quantum mechanics, they will understand what this means. It's making the sort of the impossible possible. And therefore you have to split your mind and go, split your mind and go in both ways. It's easy. If you've done it once, it's easy. Think of OpenQA. OpenQA is a success story, and it was invented some years ago to automate a tedious, unwanted task. And that was basically the idea, the role model for what happened in a knowledge management workshop by this Mr. Heigl here. And we were sitting together at SUSE earlier this year. We talked and we had an idea. What if we could just use the concepts that are in OpenQA in a way to help gathering, collecting the input for documentation automatically? Because when you write documentation, you always have to look for the stuff that needs to be documented. You have to spot the stuff that needs to be documented. And you have to find the content. And that's the problem that we have. We have a lot of data, but nobody knows where it is and that it is there. And so what if you could use automated triggers to collect this information, the changes, the news on tumbleweed, that automatically refine them and paste them into a modern dynamic, somewhat semantic portal? It's not about a new tool. And I say that because at SUSE we are very good in tool debates or in Open SUSE also, I think. And we are, it's good to question everything. But what I think of as OpenDoc is just a presentation layer for many other tools. It should be open. It should include an indexing waiting search engine with crawlers that search no matter what helpful new website of SUSE or this tiny little project somewhere would come up with. So like a modern search engine, you just throw in another URL and do some search engine language magic to wait it and have it presented. On top of this crawler that crawls websites, you could have triggers that act like agents and tell the portal, hey, I've got something. Here is something that fits into your criteria. That might be interesting. And this will be, the agents would tell that to the portal. The portal itself shows a list. I put this list in inverted commas because you will understand, after, in about 20 minutes you will know why I put this in inverted commas because this list is not a list, it's not a list, it's not a list, it's not a list. But let's just talk about it as a list. It shows a list of recent changes, problems, questions asked, or topics highly discussed or relevant or whatever. And as I said, this list is not a list, it's not a list. And this is a long slide. I hope you still understand it. I'm sure you do. It's semantics, it's weighted, it's a presentation. For example, like tech clouds, some of you may be familiar with that. This is a list. This is sort of a list, but it's a weighted list because in this list, the term web 2.0 has been searched or read or commented or disapproved in a way more than the other terms. So this is a weighted list. I would call it. I may be wrong, but it's just my naming of it to make it understandable what I think of. We also have colorful tables that compare, for example, one project with the other. In terms of, for example, how many mailing list forum discussions, how old are the versions, how many errors, mistakes are in there, whatever. So that would be a comparison, an easy visual comparison. For example, as we have in web late, some of you may know because I think there's also a talk about web late here. And web late is a tool that has a website, a dashboard, and with one view, you can see that the where document, where translation work needs to be done. For example, we have a, Kivi is 51% translated. You have a different categories with green and red and not done. So with one view, you can see things very much easier and faster than in a real list with numbers and whatever. So this is also a list, but it has some visual component in it. And the best thing is the information is already there. We have the information. So what's a trigger? A trigger could be, as I said, an agent that feeds data into an open doc. It could be any agent. Like, for example, when you have one of our mailing lists, you have this mailing list and there's a discussion going on about the latest version of system deal or whatever, and you have 200 comments, but it's only two people discussing. I would say it needs at least the topic is interesting, how many people are involved, how long is the thread. You could define a trigger that automatically puts an item on the open doc portal if one of these threads gets long enough and if some relevant people that are known as not being trolls or bots are involved. And that could trigger an entry on the portal, for example. Same applies to forums. Or you could be the standard email from OBS from OpenBuild Service telling you about the updates that they have done this week in Tambuid. But it could also be a hashtag in a commit command. If you commit, if you do git commit, just add a hashtag or whatever to your command and that would trigger an entry on the open doc portal. It could be a keyword in the release notes. It could be a special topic or a keyword in mailing list or a forum that you have been searching for. It could be predefined entities and documentation, whatever. It could also be external, like a demon monitoring social networks discussions about a topic. For example, if you're a release manager and there's a discussion going on because your latest version of your software was really messy and there were lots of mistakes inside, you would want to be informed automatically about it. So that's what an agent like that could do. And what we can, what can we get out of this, all of this data collected then aggregated into one portal? Well, something sweet and nice and tasty, I hope. Imagine an automatic and human distillery refining all this information. I have a screenshot here and I think you, Richard, will also talk about Stack Overflow later a little bit. If you know Stack Overflow, you probably already know what I'm talking about. Now, Stack Overflow also presents data in lists, but you can tag, you can vote, you can have the list, have individual views on the list. And lots of information has been, information is entered by humans here, but you can, if you click on hot, you'll have a different list or a different sorting of the same results that are in the system. And by just clicking one to five stars or did that help, whatever, the data gets more helpful to others. So this list should allow and should encourage users to rate, to mark, maybe to kick some topic as not relevant or outdated or even to tag as hot or whatever you could also create relations like this is related to virtualization or whatever. As with Stack Overflow or similar, the stuff that is rated higher will be presented more often, not relevant stuff should go down the list. In this way, and, oh no, sorry, different sentence. That also means you could have individual preferences, individual, an individual approach with your own login or whatever to this portal where you could set different types of lists because you are a user, a developer, release manager, package maintainer or whatever. You may have like your own personalized dashboard. And these criteria that you use could like define relevance for single users for you because you might be different. Different in a way. Some movie fans will have recognized. Like the good, the bad, the ugly. The release managers or developers could use OpenDoc or such a dashboard to find out what's wrong, working good, bad, ugly about their own project. Individual dashboards I've already said that it could also be live tracking of development if OBS or if triggers deliver constantly, constantly deliver data. And it could also be used for analytics like the comparison of projects or tasks like Weblate. We have lots of this stuff. We have lots of the, we have all the data. We also have some websites like that. What I'm talking about is sort of an aggregation, a portal that aggregates that. And at this point, we were talking about, well, how could we, how could this technically work? What could be used as basis for such a portal to fulfill those needs that I talked about? And that is where the knowledge management expert came in. And at this point, I just give, pass the microphone on to Richard because he can tell us and give us some examples about how the Wiki World might help us in that. Hi there. Thank you for being here. So my part in this talk is that I share a few experiences we have made in the Wiki World of the last 10 years because we have seen that there is not only a community, there is, there are thousands of information, there is knowledge sharing. You have unbelievable many sources. And how can we cope with that? And some people would say, okay, yeah, Wiki is something, this is like Wikipedia, it's a bit old fashioned. And I don't think so. Wiki has principles and has shown many ways how we can collaboratively share knowledge and aggregate knowledge and bring people together and bring some structure in this whole process. So what I will do now in this talk are two things. First, I will give you such a few ideas how we can start the process to improve the documentation and how we can automate it. And the second thing is I would show you three websites. They can give, have some ideas what's possible. And this is for the next discussion, I think, could be very interesting. So always if it comes to organize, start a knowledge platform, doesn't matter what it is, for what it is, you have to do a few things. The first thing is you have to answer the question, how do we retrieve knowledge? How do we, can you find knowledge today? So Marcus already said, yes, we need a proper search. That's always the basis. We have many guys out there thinking that a search is everything. A search can do everything. A search can do a lot. And yes, it's true. And I'll show you a few examples that a semantic search and good filters will help us a lot to do that. It's not about, again, it's not about tools today, but this is the experiences we made and this experience and the way we are going and heading to today, even Wikipedia and Wikipedia communities around the world. What is semantic? Maybe just for a few people who don't know what it is. Semantic is a funny word for something. Very easy. You learn how to work with meter data, structured data like the author of an article, expiry dates, build numbers or whatever. And normally you have all these information in the content somewhere hidden and that a search can use it. You must set a markup and say, this is a date and this is an author. And then you can do really great things with that. Another thing I want to mention and really want to emphasize is that if it comes to knowledge, you need unique IDs. Wikipedia offers only one article per topic and works with redirects and that for very, very, very good reasons. So if you see it's like overflow, then you can start any topic you want to. Oh, this is Richard's library. I want to talk about the library of Richard's library page and something on you. Find five places or 10 places discussing the same stuff, documenting the same stuff. And in Wikipedia, you are forced, people are forced to use one page and one article to talk about. And because human beings are not really good in memorizing numbers and data, it's normally an article, an article title. And this is something we have to head for that one thing, if you have some information, some knowledge, you should attribute, you should attach it to one point and then you can start and you will find things much better and your search will find it much easier. The next thing is, okay, how will we collect knowledge? And now you see, you can make it on your own, you have ordinary authors, but you can do a lot of these things together with your tools. You can automate it. So Mark has said already, okay, let's define some triggers. Somewhere out there, there is an important information. This information will come to the new open.platform and will make a new post. Hi, here has something changed. Maybe for somebody is this interesting. Other things, engines can do much better than human beings normally is changing meter data. Oh, that's a new release number. So you don't have to change that in many ways. On many platforms do it once or let it do it your platform. Next thing is, now you need human beings for classification. It's always the same. You can say, okay, this information belongs to another article. You can map it. You can say, okay, there is something similar. There are dependencies. There are other topics and you can rate these information. You can say that it has a high quality or is an important change for us and other people should see it. Things you can do, maybe a bot can do, but normally ordinary people do it, enrich your content, add some screenshots, diagrams, videos, attachment, whatever. So OpenDoc can collect all these things. But it also should make some proposal for us to do. So it can tell us, hey, there are links missing. There are often expired posts. Old and not confirmed pages. That's what they do at Wikipedia. Old and not confirmed pages is a very important thing to make the quality assurance in Wikipedia and Wikipedia similar platforms. References, resources. I will hurry up with that. And the other thing is, okay, you want to stay informed. So an ordinary thing is, which is common, is you can follow a topic. You can follow the category. You have your stream. You have your own task list. All these things is very common. But this should be brought together in the plan. You have different ways to work this, but you should put the right ones. This is the question we have to answer now. Last thing, Wikipedia, it here's to its versioning system. That's often forgotten. It's very, very important that you have control over what has changed. Even if the bot has changed it or your neighbor, it doesn't matter. You have to see what has changed. And maybe you must make some rollbacks to that. So, and last one is, obviously, you must find ways to archive. You must have ways to delete information and knowledge. That's, that are things most people don't see at Wikipedia, but it happens every day. They have a huge process for deleting information and not only deletion discussions, but also automatic forms for, get rid of outdated information. So a few examples. That's the second part. We talked already about Stack Overflow. So I don't want to get too deep into that. I show you three other platforms. One is Shift Lock. That's a customer's project. We realized this year. And I will show you a bit about streaming, about attributions, filters and semantic. Research is about, is a head-resort platform. Quite funny. I love it because of the search there. And Translate Wiki is a translation platform for the Wiki communities and for open source software projects. And they can show us a bit about task lists. Oh, there it is. Okay. Yes. Unfortunately, this is German because it's for a German company. The story behind that is, there's a huge amount of, they have to document a plant somewhere here in Germany. And they have people who are responsible to maintain the plant. And they need a book or they need a list. What should we, what have we done? What is to improve? We have some messages. And the thing is, Shift Book is a Shift Book. So what you see now, this is actually, this is a media Wiki on, in the basis. It has just a different view and another skin. And you see, okay, there are messages from people. Somebody has changed something anywhere. And it doesn't depend if this message is made by a human being or by a botter. So it's just about how it works. And what I want to show you, that's a bit complicated. So let this be, for instance, an article about a library, some Linux library. And then you have a description what it is. This is still a Wiki text. But you can enrich this with metadata, what it is. It has a number, an ID, something else. And you have messages to that build, for instance. So what we have seen at the last page, you see, okay, you can attribute, you can attach this to that. And for instance, I show you why it's semantic. If you are working with semantic, then you mostly, you offer your authors, you make it much easier for them to add it something. Because you say, okay, you have here a free text field. But you have also, if you want to add some data or other stuff, then people shouldn't think about how the logic is behind that you can do it, make it most automatically. So anyway, so now you produce metadata and text and everything. And it makes it possible that you can get some reports. So you can say, okay, give me all messages, whether something went wrong or use or maintenance reports or so. So now let's transform this into the problem we have in an open docs system. It's the same thing. It's the completely same thing. You have an article about a package. And then you have messages around that. You have discussions about it. You have maybe some posts made by the GitHub or somewhere else. And you want to attach this to that topic you're talking about. And this will make it much easier to find for people who are working with that, other person, others, people from the doc team, people from the community, what is going on on this topic. And it makes it much easier for the search to find it because you follow the Vicky way. You have always one unique idea. You know what the name of the problem is. And then you find everything around. Another thing is, no, it's the same window. This is a head or a special page. This is also media Vicky. And there you can search for something typical question for head or is what is about scissors. And then you get some results. You see here these are ordinary articles about scissors. And these are for instance, these are links. These are sources somewhere out in the web. If I would jump to that, then I come to another website. And this website has different categories or tags. And we can an idea behind this platform is to rate this information that you can see, okay, this article has a high quality or is especially for has good images or videos or something from a marshmallow that I know. Again, it's just about the principle. The principle is you have a great, nice search and everything you do, you combine it with good content. And you work in an intelligent way in combining categories, free text, search, and you will find everything very, very quick. You see, this is really quick searching. Yes. And a third one. Ha, no, unfortunately we need this one. Okay, Translate Vicky is an open source translation community. And it works like this. I don't know what to do today. Or maybe I can translate something for an open source community project. So I go to translate Vicky. And there are several projects. And it's the same like the translation tool you showed us before. You see, what's it like? Start it. What if I want to do it for you? I don't know. Sorry, it doesn't work. Okay. I let this, it's about, you go to your page and you see, okay, there are 10, 20 tasks I can do. I have several translations. I open it, take the translation, post it and everything is fine. So I can work as long as I want. And every little thing I do will improve the documentation. So what they do is everything you have to do for this documentation or improving the translation is very small steps, very small packages, no workload. You just control and say, okay, this is fine. This is not fine. And I can do it better. And this is the way I think we should go to is that we make small packages and you can say, oh, is this page outdated? Yes or not? Does it have a screenshot? Yes or not? Do you know better sources? Is this discussion really important? And then you get a great, a really, really, really great documentation. I can promise you. And what we have already at this moment, it's not a technical thing. It's a question about people and the content. Our experience is if you start any web platform, it's always about people and what content you really need because there's a huge amount. But in the end, you need at least 10%. 10% are what you're really, really looking for and the others are interesting. But so for a success story, you need these 10%. And this is what we are discussing today. What is necessary? And if you know what is necessary, then you can organize this very quickly. So I give back to Marcus Fahner. Thank you very much. Thank you, Richard. Okay, I close the presentation. I wanted to close this. So what we are going to do, or this is all, as I said, this is all up to now ideas. I want to put this for discussion. This is for general discussion. The documentation team will provide one person's work for one day per week to help as a gardener inside this. If there is something like an open doc portal one day, I added it as a hack week project for next week. And now here is my presentation again. Let me just see. Can I, yeah, I can jump to the one, let the one. I would like to carry on this, this cut thing, this cut thing, whole thing. So because knowledge sharing is not only a question of technology, it is also a question of people and content. As we have seen, there are many ways where we can get the content from somewhat or semi-automatic systems, but we also need people who do that. And we need to know if this is wanted and if it is feasible for us at all. And therefore, as I already mentioned, we have something in mind like the gardener, which I am already saying that I have the permission to devote one guy, one person of my team for one day a week, some hours of work to refine the results of the triggers. Hopefully, the community would have helped before that by rating, marking, tagging, whatever. But he would work in that because I think that's necessary, separating the weeds from the good, from the flowers. We already started to work on the open-suzer documentation. So Christoph, I think he's not, yeah, here he is. He already started working in the Viki. We have some administrative tasks like moving the Viki, updating, upgrading it and making it a starting place for documentation, for open-suzer documentation. We are working on that. That is already work in progress. But I want to go on, I want to move on with this. I want you, the open-suzer community, to tell me if this is something that is good or that is bad. I want to give this open doc thing for discussion, to put it for discussion for you. And so next week is Hack Week. And therefore, I added this as a Hack Week project. It's the Project 1514. And I hereby invite you to join me, us for that. And that's why now I'm open for discussions. We have a little more time because the next, I know the next speaker quite well. And he promised that he wouldn't start before I leave the stage. So if you have any questions, if you want to tell me that this is total bullshit that I just talked, which I don't think will happen because I had an expert here. Thank you, Richard. So, any questions? Was it that much input? Or was it that stupid? Or both? It needs to settle, huh? So, the next steps would involve, like I said, the Hack Week project or the Hack Week maybe discussions next week. Question? No. Oh, okay. Also waiting. So the next step would involve the Hack Week. Next week, with discussions. And finding out if there is interest in the community in this project. And then we will see. I hope that we can start something and make something here. And have some nice summer months working on that. Maybe something like a summer of documents with having something that we can present at the SuzyCon in November, whatever. Okay. You've had your chance to ask questions. Thank you. Thank you, Richard. No worries.
 So, hello everybody and welcome here in this audience and thank you for coming as so many  people and hi to all the millions and billions in the different variety of the Internet's  out there. I'm Marcus Farner. I'm happy to have you here. Thank you. Thank you. Oh, that's  it. That's all I wanted. Goodbye. No. I'm here to present an idea and I am fully aware  that this, that I am presenting here is the produce of a lot of talking, quite some beer  were involved in fact and quite some ideas are involved and it is, it is nothing that  is finished of course. It's just an idea and I am here because we want to hear from you,  the open Susie community, what you think about it and if you think this is possible and we  are basically we are trying to make something impossible. It's about automating documentation  which is impossible and you will see that. Well, I'm here. I'm Marcus Farner. Some of  you may know me, I guess. And with me is, I'll tell you about me. With me is Richard  Heigl from Hello World. Richard Heigl is an expert in knowledge management and in the  course of this talk I will tell you why he is here. I am team leader at Susie for documentation  and I am absolutely impartial. I was an open source journalist and that's why I am absolutely  neutral. Some people say I am a Linux expert. I wouldn't say no, I'm not. I would say no,  I'm not. I have been working with Linux since 1994 and I have quite some other maybe interesting  stories to tell. I am a conch diplomat, I'm a priest. I'm a Jedi knight, I'm Encelado  citizen number four and I own some property on the moon. And my boss says I'm running  through the worst. So that's what I hear from one of my colleagues recently. If you want  to know more details about either one of these things, just talk to me and ask me about it.  And for the non-German speakers, if you feel any emotions involved with this talk, which  I think will be inevitable, just get some hugs for that. So I want this thing, as I  said, it's something for discussion. I want to hear, we want to hear what you think about  it. All of these next sentences will be, I guess, maybe controversial, more or less.  I think open source communities do not write documentation. You can always contradict me,  prove the opposite. You think they do? I think, do you think I'm right? Thank you,  Jürgen. Next one. Developers want to write code, not documentation. I just said this  several. Every open source project needs documentation. And documentation cannot be  automated. There's always humans who have to write documentation in the end. Though good  software should not need documentation, it should be self-explanatory, proper documentation,  resources are essential to attract new users. It's mostly the newbies or the ones who are  new to something who need documentation. Tumbleweed is a rolling release. No, yes, it  is. And it's moving way too fast to be properly documented. Nobody disagrees?  Good. Seems like I did my homework at least a little. Nevertheless, there's a lot of  data. We have a lot of information that we are gathering. We have data in this open  source of Wiki. We have data in the mailing lists where people discuss solutions and discuss  about good or bad solutions to problems. We have stuff even in the build service. The  build service has a lot of information about version numbers and more. We have information  in forums and release notes and get comments. And there's the documentation that we, the  SUSE documentation team, provide. We develop new forms of documentation like the SUSE best  practices. So, sort of like modern style how-tos for achieving single tasks with SUSE products.  So there's a lot of documentation. And that's not all. That's just what I just, this was  the point that out here. It's just a little bit, a little tiny bit of the documentation  that is around in open SUSE. And in SUSE, and there's even more with some other projects  somewhere out there, anywhere, there's still even more stuff somewhere in other forums  outside. So, what? This picture is hanging over here. I thought it was in the other room,  so I put this picture here. It says, this ball painting, it says, if what you say is  true, the Shaolin and Kogan could be dangerous. And I think this is pretty much what's happening  here. We have some, we have five facts and I think it's, there is a solution, there may  be a solution to it. Community and documentation are difficult couple. Oops. Wrong. What is  it? Jump over. We have a lot of information in a lot of places. I took this picture last  week on a longer holiday trip to northern Germany. It's a beautiful beach. It's called  the Amber Beach. And if you dig a little bit, on the beach, you'll find quite some worthy  stones, some gems. And it's, and that's what it's all about. It's about finding and presenting  it. We have lots of information, but we fail in finding and presenting it. And I, and now  we come to the last one. The last fact, or the one before last fact, Tumbleweed is changing  faster than anybody can document. Oh, really, I don't believe that. We can do better because  nothing is written in stone. That's why I want to introduce the idea of OpenDoc. OpenDoc  is just the name that I thought about for this project because I think it just fits.  And it's sort of, for those, for those among you who know about quantum mechanics, they  will understand what this means. It's making the sort of the impossible possible. And therefore  you have to split your mind and go, split your mind and go in both ways. It's easy. If  you've done it once, it's easy. Think of OpenQA. OpenQA is a success story, and it was invented  some years ago to automate a tedious, unwanted task. And that was basically the idea, the  role model for what happened in a knowledge management workshop by this Mr. Heigl here.  And we were sitting together at SUSE earlier this year. We talked and we had an idea. What  if we could just use the concepts that are in OpenQA in a way to help gathering, collecting  the input for documentation automatically? Because when you write documentation, you  always have to look for the stuff that needs to be documented. You have to spot the stuff  that needs to be documented. And you have to find the content. And that's the problem  that we have. We have a lot of data, but nobody knows where it is and that it is there. And  so what if you could use automated triggers to collect this information, the changes,  the news on tumbleweed, that automatically refine them and paste them into a modern dynamic,  somewhat semantic portal? It's not about a new tool. And I say that because at SUSE we  are very good in tool debates or in Open SUSE also, I think. And we are, it's good to question  everything. But what I think of as OpenDoc is just a presentation layer for many other  tools. It should be open. It should include an indexing waiting search engine with crawlers  that search no matter what helpful new website of SUSE or this tiny little project somewhere  would come up with. So like a modern search engine, you just throw in another URL and  do some search engine language magic to wait it and have it presented. On top of this crawler  that crawls websites, you could have triggers that act like agents and tell the portal,  hey, I've got something. Here is something that fits into your criteria. That might be  interesting. And this will be, the agents would tell that to the portal. The portal itself  shows a list. I put this list in inverted commas because you will understand, after,  in about 20 minutes you will know why I put this in inverted commas because this list  is not a list, it's not a list, it's not a list, it's not a list. But let's just talk  about it as a list. It shows a list of recent changes, problems, questions asked, or topics  highly discussed or relevant or whatever. And as I said, this list is not a list, it's  not a list. And this is a long slide. I hope you still understand it. I'm sure you do.  It's semantics, it's weighted, it's a presentation. For example, like tech clouds, some of you  may be familiar with that. This is a list. This is sort of a list, but it's a weighted  list because in this list, the term web 2.0 has been searched or read or commented or  disapproved in a way more than the other terms. So this is a weighted list. I would call it.  I may be wrong, but it's just my naming of it to make it understandable what I think of.  We also have colorful tables that compare, for example, one project with the other. In  terms of, for example, how many mailing list forum discussions, how old are the versions,  how many errors, mistakes are in there, whatever. So that would be a comparison, an easy visual  comparison. For example, as we have in web late, some of you may know because I think  there's also a talk about web late here. And web late is a tool that has a website, a dashboard,  and with one view, you can see that the where document, where translation work needs to  be done. For example, we have a, Kivi is 51% translated. You have a different categories  with green and red and not done. So with one view, you can see things very much easier  and faster than in a real list with numbers and whatever. So this is also a list, but  it has some visual component in it. And the best thing is the information is already there.  We have the information. So what's a trigger? A trigger could be, as I said, an agent that  feeds data into an open doc. It could be any agent. Like, for example, when you have one  of our mailing lists, you have this mailing list and there's a discussion going on about  the latest version of system deal or whatever, and you have 200 comments, but it's only  two people discussing. I would say it needs at least the topic is interesting, how many  people are involved, how long is the thread. You could define a trigger that automatically  puts an item on the open doc portal if one of these threads gets long enough and if some  relevant people that are known as not being trolls or bots are involved. And that could  trigger an entry on the portal, for example. Same applies to forums. Or you could be the  standard email from OBS from OpenBuild Service telling you about the updates that they have  done this week in Tambuid. But it could also be a hashtag in a commit command. If you commit,  if you do git commit, just add a hashtag or whatever to your command and that would trigger  an entry on the open doc portal. It could be a keyword in the release notes. It could  be a special topic or a keyword in mailing list or a forum that you have been searching  for. It could be predefined entities and documentation, whatever. It could also be external, like  a demon monitoring social networks discussions about a topic. For example, if you're a release  manager and there's a discussion going on because your latest version of your software  was really messy and there were lots of mistakes inside, you would want to be informed automatically  about it. So that's what an agent like that could do. And what we can, what can we get  out of this, all of this data collected then aggregated into one portal? Well, something  sweet and nice and tasty, I hope. Imagine an automatic and human distillery refining  all this information. I have a screenshot here and I think you, Richard, will also talk  about Stack Overflow later a little bit. If you know Stack Overflow, you probably already  know what I'm talking about. Now, Stack Overflow also presents data in lists, but you can tag,  you can vote, you can have the list, have individual views on the list. And lots of information  has been, information is entered by humans here, but you can, if you click on hot, you'll  have a different list or a different sorting of the same results that are in the system.  And by just clicking one to five stars or did that help, whatever, the data gets more  helpful to others. So this list should allow and should encourage users to rate, to mark,  maybe to kick some topic as not relevant or outdated or even to tag as hot or whatever  you could also create relations like this is related to virtualization or whatever. As  with Stack Overflow or similar, the stuff that is rated higher will be presented more  often, not relevant stuff should go down the list. In this way, and, oh no, sorry, different  sentence. That also means you could have individual preferences, individual, an individual approach  with your own login or whatever to this portal where you could set different types of lists  because you are a user, a developer, release manager, package maintainer or whatever. You  may have like your own personalized dashboard. And these criteria that you use could like  define relevance for single users for you because you might be different. Different in  a way. Some movie fans will have recognized. Like the good, the bad, the ugly. The release  managers or developers could use OpenDoc or such a dashboard to find out what's wrong,  working good, bad, ugly about their own project. Individual dashboards I've already said that  it could also be live tracking of development if OBS or if triggers deliver constantly,  constantly deliver data. And it could also be used for analytics like the comparison  of projects or tasks like Weblate. We have lots of this stuff. We have lots of the, we  have all the data. We also have some websites like that. What I'm talking about is sort  of an aggregation, a portal that aggregates that. And at this point, we were talking about,  well, how could we, how could this technically work? What could be used as basis for such  a portal to fulfill those needs that I talked about? And that is where the knowledge management  expert came in. And at this point, I just give, pass the microphone on to Richard because  he can tell us and give us some examples about how the Wiki World might help us in that.  Hi there. Thank you for being here. So my part in this talk is that I share a few experiences  we have made in the Wiki World of the last 10 years because we have seen that there is  not only a community, there is, there are thousands of information, there is knowledge  sharing. You have unbelievable many sources. And how can we cope with that? And some people  would say, okay, yeah, Wiki is something, this is like Wikipedia, it's a bit old fashioned.  And I don't think so. Wiki has principles and has shown many ways how we can collaboratively  share knowledge and aggregate knowledge and bring people together and bring some structure  in this whole process. So what I will do now in this talk are two things. First, I will  give you such a few ideas how we can start the process to improve the documentation and  how we can automate it. And the second thing is I would show you three websites. They can  give, have some ideas what's possible. And this is for the next discussion, I think,  could be very interesting. So always if it comes to organize, start a knowledge platform,  doesn't matter what it is, for what it is, you have to do a few things. The first thing  is you have to answer the question, how do we retrieve knowledge? How do we, can you  find knowledge today? So Marcus already said, yes, we need a proper search. That's always  the basis. We have many guys out there thinking that a search is everything. A search can  do everything. A search can do a lot. And yes, it's true. And I'll show you a few examples  that a semantic search and good filters will help us a lot to do that. It's not about,  again, it's not about tools today, but this is the experiences we made and this experience  and the way we are going and heading to today, even Wikipedia and Wikipedia communities around  the world. What is semantic? Maybe just for a few people who don't know what it is. Semantic  is a funny word for something. Very easy. You learn how to work with meter data, structured  data like the author of an article, expiry dates, build numbers or whatever. And normally  you have all these information in the content somewhere hidden and that a search can use  it. You must set a markup and say, this is a date and this is an author. And then you  can do really great things with that. Another thing I want to mention and really want to  emphasize is that if it comes to knowledge, you need unique IDs. Wikipedia offers only  one article per topic and works with redirects and that for very, very, very good reasons.  So if you see it's like overflow, then you can start any topic you want to. Oh, this  is Richard's library. I want to talk about the library of Richard's library page and  something on you. Find five places or 10 places discussing the same stuff, documenting  the same stuff. And in Wikipedia, you are forced, people are forced to use one page  and one article to talk about. And because human beings are not really good in memorizing  numbers and data, it's normally an article, an article title. And this is something we  have to head for that one thing, if you have some information, some knowledge, you should  attribute, you should attach it to one point and then you can start and you will find things  much better and your search will find it much easier. The next thing is, okay, how will we  collect knowledge? And now you see, you can make it on your own, you have ordinary authors,  but you can do a lot of these things together with your tools. You can automate it. So Mark  has said already, okay, let's define some triggers. Somewhere out there, there is an  important information. This information will come to the new open.platform and will make  a new post. Hi, here has something changed. Maybe for somebody is this interesting. Other  things, engines can do much better than human beings normally is changing meter data. Oh,  that's a new release number. So you don't have to change that in many ways. On many  platforms do it once or let it do it your platform. Next thing is, now you need human  beings for classification. It's always the same. You can say, okay, this information  belongs to another article. You can map it. You can say, okay, there is something similar.  There are dependencies. There are other topics and you can rate these information. You can  say that it has a high quality or is an important change for us and other people should see  it. Things you can do, maybe a bot can do, but normally ordinary people do it, enrich  your content, add some screenshots, diagrams, videos, attachment, whatever. So OpenDoc can  collect all these things. But it also should make some proposal for us to do. So it can  tell us, hey, there are links missing. There are often expired posts. Old and not confirmed  pages. That's what they do at Wikipedia. Old and not confirmed pages is a very important  thing to make the quality assurance in Wikipedia and Wikipedia similar platforms. References,  resources. I will hurry up with that. And the other thing is, okay, you want to stay informed.  So an ordinary thing is, which is common, is you can follow a topic. You can follow  the category. You have your stream. You have your own task list. All these things is very  common. But this should be brought together in the plan. You have different ways to work  this, but you should put the right ones. This is the question we have to answer now.  Last thing, Wikipedia, it here's to its versioning system. That's often forgotten. It's very,  very important that you have control over what has changed. Even if the bot has changed  it or your neighbor, it doesn't matter. You have to see what has changed. And maybe you  must make some rollbacks to that. So, and last one is, obviously, you must find ways  to archive. You must have ways to delete information and knowledge. That's, that are things most  people don't see at Wikipedia, but it happens every day. They have a huge process for deleting  information and not only deletion discussions, but also automatic forms for, get rid of outdated  information. So a few examples. That's the second part. We talked already about Stack  Overflow. So I don't want to get too deep into that. I show you three other platforms.  One is Shift Lock. That's a customer's project. We realized this year. And I will show you  a bit about streaming, about attributions, filters and semantic. Research is about,  is a head-resort platform. Quite funny. I love it because of the search there. And Translate  Wiki is a translation platform for the Wiki communities and for open source software projects.  And they can show us a bit about task lists. Oh, there it is. Okay. Yes. Unfortunately,  this is German because it's for a German company. The story behind that is, there's a huge amount  of, they have to document a plant somewhere here in Germany. And they have people who  are responsible to maintain the plant. And they need a book or they need a list. What  should we, what have we done? What is to improve? We have some messages. And the thing is,  Shift Book is a Shift Book. So what you see now, this is actually, this is a media Wiki  on, in the basis. It has just a different view and another skin. And you see, okay,  there are messages from people. Somebody has changed something anywhere. And it doesn't  depend if this message is made by a human being or by a botter. So it's just about how it  works. And what I want to show you, that's a bit complicated. So let this be, for instance,  an article about a library, some Linux library. And then you have a description what it is.  This is still a Wiki text. But you can enrich this with metadata, what it is. It has a number,  an ID, something else. And you have messages to that build, for instance. So what we have  seen at the last page, you see, okay, you can attribute, you can attach this to that.  And for instance, I show you why it's semantic. If you are working with semantic, then you  mostly, you offer your authors, you make it much easier for them to add it something.  Because you say, okay, you have here a free text field. But you have also, if you want  to add some data or other stuff, then people shouldn't think about how the logic is behind  that you can do it, make it most automatically. So anyway, so now you produce metadata and  text and everything. And it makes it possible that you can get some reports. So you can  say, okay, give me all messages, whether something went wrong or use or maintenance reports or  so. So now let's transform this into the problem we have in an open docs system. It's the same  thing. It's the completely same thing. You have an article about a package. And then  you have messages around that. You have discussions about it. You have maybe some posts made by  the GitHub or somewhere else. And you want to attach this to that topic you're talking  about. And this will make it much easier to find for people who are working with that,  other person, others, people from the doc team, people from the community, what is going  on on this topic. And it makes it much easier for the search to find it because you follow  the Vicky way. You have always one unique idea. You know what the name of the problem  is. And then you find everything around. Another thing is, no, it's the same window. This is  a head or a special page. This is also media Vicky. And there you can search for something  typical question for head or is what is about scissors. And then you get some results. You  see here these are ordinary articles about scissors. And these are for instance, these  are links. These are sources somewhere out in the web. If I would jump to that, then  I come to another website. And this website has different categories or tags. And we can  an idea behind this platform is to rate this information that you can see, okay, this article  has a high quality or is especially for has good images or videos or something from  a marshmallow that I know. Again, it's just about the principle. The principle is you  have a great, nice search and everything you do, you combine it with good content. And  you work in an intelligent way in combining categories, free text, search, and you will  find everything very, very quick. You see, this is really quick searching. Yes. And a  third one. Ha, no, unfortunately we need this one. Okay, Translate Vicky is an open source  translation community. And it works like this. I don't know what to do today. Or maybe I  can translate something for an open source community project. So I go to translate Vicky.  And there are several projects. And it's the same like the translation tool you showed  us before. You see, what's it like? Start it. What if I want to do it for you? I don't  know. Sorry, it doesn't work. Okay. I let this, it's about, you go to your page and  you see, okay, there are 10, 20 tasks I can do. I have several translations. I open it,  take the translation, post it and everything is fine. So I can work as long as I want.  And every little thing I do will improve the documentation. So what they do is everything  you have to do for this documentation or improving the translation is very small steps, very  small packages, no workload. You just control and say, okay, this is fine. This is not fine.  And I can do it better. And this is the way I think we should go to is that we make small  packages and you can say, oh, is this page outdated? Yes or not? Does it have a screenshot?  Yes or not? Do you know better sources? Is this discussion really important? And then  you get a great, a really, really, really great documentation. I can promise you. And  what we have already at this moment, it's not a technical thing. It's a question about  people and the content. Our experience is if you start any web platform, it's always  about people and what content you really need because there's a huge amount. But in the  end, you need at least 10%. 10% are what you're really, really looking for and the others  are interesting. But so for a success story, you need these 10%. And this is what we are  discussing today. What is necessary? And if you know what is necessary, then you can organize  this very quickly. So I give back to Marcus Fahner. Thank you very much.  Thank you, Richard. Okay, I close the presentation. I wanted to close this. So what we are going  to do, or this is all, as I said, this is all up to now ideas. I want to put this for discussion.  This is for general discussion. The documentation team will provide one person's work for one  day per week to help as a gardener inside this. If there is something like an open doc portal  one day, I added it as a hack week project for next week. And now here is my presentation  again. Let me just see. Can I, yeah, I can jump to the one, let the one. I would like  to carry on this, this cut thing, this cut thing, whole thing. So because knowledge  sharing is not only a question of technology, it is also a question of people and content.  As we have seen, there are many ways where we can get the content from somewhat or semi-automatic  systems, but we also need people who do that. And we need to know if this is wanted and  if it is feasible for us at all. And therefore, as I already mentioned, we have something in  mind like the gardener, which I am already saying that I have the permission to devote  one guy, one person of my team for one day a week, some hours of work to refine the results  of the triggers. Hopefully, the community would have helped before that by rating, marking,  tagging, whatever. But he would work in that because I think that's necessary, separating  the weeds from the good, from the flowers. We already started to work on the open-suzer  documentation. So Christoph, I think he's not, yeah, here he is. He already started  working in the Viki. We have some administrative tasks like moving the Viki, updating, upgrading  it and making it a starting place for documentation, for open-suzer documentation. We are working  on that. That is already work in progress. But I want to go on, I want to move on with  this. I want you, the open-suzer community, to tell me if this is something that is good  or that is bad. I want to give this open doc thing for discussion, to put it for discussion  for you. And so next week is Hack Week. And therefore, I added this as a Hack Week project.  It's the Project 1514. And I hereby invite you to join me, us for that. And that's why  now I'm open for discussions. We have a little more time because the next, I know the next  speaker quite well. And he promised that he wouldn't start before I leave the stage.  So if you have any questions, if you want to tell me that this is total bullshit that  I just talked, which I don't think will happen because I had an expert here. Thank you, Richard.  So, any questions? Was it that much input? Or was it that stupid? Or both?  It needs to settle, huh? So, the next steps would involve, like I said, the Hack Week  project or the Hack Week maybe discussions next week. Question?  No.  Oh, okay. Also waiting. So the next step would involve the Hack Week. Next week, with discussions.  And finding out if there is interest in the community in this project. And then we will  see. I hope that we can start something and make something here. And have some nice summer  months working on that. Maybe something like a summer of documents with having something  that we can present at the SuzyCon in November, whatever. Okay. You've had your chance to  ask questions. Thank you. Thank you, Richard.  No worries.
Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_0_7487.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_7488_8903.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_8904_9431.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_9432_11027.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_11028_11819.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_11820_12167.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_12168_13691.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_13692_18335.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_18336_18803.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_18804_19019.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_19020_19139.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_19140_19187.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_19188_22895.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_22896_23123.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_23124_23735.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_23736_23819.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_23820_23891.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_23892_24011.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_24012_26351.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_26352_26399.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_26400_38399.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_38400_43739.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_43740_43835.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_43836_46763.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_46764_48359.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_48360_52799.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_52800_53003.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_53004_53687.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_53688_53975.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_53976_55091.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_55092_56135.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_56136_57131.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_57132_57203.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_57204_57263.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_57264_57335.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_57336_57479.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_57480_58007.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_58008_64763.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_64764_64907.png Markus_Feilner__OpenDOC__Automating_Documentation_iXV5z6KpVe8_64908_65025.png