i'm getting the feeling that have documentation it team is actually in this room right now so the docking station team has excess this for almost as long as the name project came around and i know it's not with they may snow who were inspired by the red hat labs to write the contention for them and i turned out to be he happened to be really good that and manage the process knowledge onto the rest of the community and that's how we ended up with a docking station team in the first place the month was passed from person to person for few years and eventually shown what can send that out dictator and two thousand three and this year will be his tenth anniversary of the september and eventually we came to name three but that a definite i think three has a question sean has millions and some of them are actually here thank you got millions and he makes good use of us people so it's around all the time who are the contention team well we don't really have a i know E to do something about that it's not enough are you going to submit a patch today one was a committed okay well that i forgot that france the first time i was just think that from memory and there are actually we have about fifty applications that we maintain documentation for on the top of that we have developer documentation the system administrator guys at actually no single person can really keep track of all of that which is probably why i missed your patch and we don't have a formal team structure we have shown results and then we have all of us to do all the work and the we have members who are native english speakers we have people who are not everyone has something to contributes we have over the last year we had twenty five notable contributors seven of whom made significant contributions to lots and lots of projects we have we actually take most of intense for that speech program we have five mentors for willing to mentor intense cordless on the name of page we actually taken things outside of the program as well but is less formally so and that was four years we actually have twelve intense for whom i with us today in this room and up there we go for and six of us and now foundation numbers which i think is actually pretty successful i think we've done really well so we're as we came along we decided welsh on the slide that side he wanted to improve the user documentation and experience for users so previously i can and two minutes of the help was written in top or which is really good for developer help but not actually so good for user help because the first thing you see when you look at the dot book how a double help is just a blank page with an index that's not really very useful i don't help was also written and the hierarchical a structural and focus on describing the user interface and actually who wants to read through a description of the user interface to find out how to achieve some and you want okay the lakers so with names three because the user interface change too much between them two and three and also may of applications change we choose to rewrite the hell in model at which was which is next the mel languages which was designed by sean specifically for user help it when you look a lot of help i mean you will to talk will help it looks very different it's much more task oriented so wanna use a reason to help they generally have like they have something they want to achieve they look at the user help and they find how to achieve that so instructions how to achieve something rather than have the user interface and thus as i mentioned this to we have a team members from all over the world we tend to write in simple english because firstly it's easier to translate saintly and you want all or nothing you want but may people find it much easier to write and actually many people find it much easier to understand as well and as it turns out it's pretty important because actually user help is not translated very well i we don't have very many translations as you can see from them to name three there has not been much change most of the user hell translations so it's under ten percent translate that i'm sorry most languages the user help is translate the on the simpsons we use help translate that we have had only one language consistently translated to be nine percent if i'd almost a hundred percent at every release and that the spanish so we really appreciate that and would be great if we can somehow encouraged translators to actually translate the user i'll tell you why that's important and that's so our users we have a lot of users gently they're not people who are sitting in this room that help is designed for people who actually don't know how to use application at all all people who have used for many years and we still get it's all useful for people who are here for example if the user interface changes and something you can find some "'cause" the user help well that you will find out that or maybe it's a speech which has been okay i have everything so we can't actually track who reads the desktop help which are construct who reads what they find useful what they didn't find useful the best reviews we gets are actually from translators because they often file bugs within seven days of documents so which is really high because that's long before release usually so we can actually fix things i mean within the team we have a review process as well where in the hell will normally be reviewed by three different people on the other hand users germany and get the runt reporting box six months after the release which can be up to a year after the page was right and this means that so very often by the time they report the but either the U I has changed an application the help as being very rewritten or the problem has already been fixed and if it's and mastery germany but sometimes they might not actually be able to get the fixed without suppression if they might have to actually with another six months to see the fix which isn't very user friendly thanks to hundred every we have actually recently being able to try are uses on like we don't know about or which has proven to be really handy as you can see a it's a particularly good so i've got but you can see the trends and so what that shows is the blue line is unique that's the magenta is unique page fees and the yellow is all each fees on average we get approximately six thousand unique page views a date which is much more than many of the other and then website this by the way covers a user hell and developer help and the system administrator guide and as you can see the trend shows that so we have the most page views on weekdays and that implies that so many of our users for beating the websites are doing so at or rather than which is quite surprising i was actually expecting for most of our users to be using to be reading the help but that's not the case yes when there's nothing on T V and actually along with that's what we found was that the spanish translations all the user help i've been bred much more often than the ritual use help and this is why translations are importance eight out of the top ten read pay most read pages between the user help and the developer documentation happiness five a forced now she's is so that if you pay a few waste that developers and designers can actually help us improve the help before the release because of course we always want to provide the best hope that we can for users so for example designer a applications gonna have tool tips because a button does hasn't in icon so know text then it's very difficult for us to describe and we also need to talk about how to interact with the user interface and will help of design is actually try to top themselves through is as well because if they're not able to describe how user should be interacting with a specific button or label then we probably quantity there so you know they can come talk us or even just come up with a way to describe it themselves and i will help us quite a lot and as for developers and we do try to keep on top of user help on them and time and have it done time for the releases but sometimes you know we don't know about the changes or we can't actually test the latest application easily so we might need help just building it even so that we can see the what it should look like and whether they have been any changes so please file bugs against the have dogs well then when there you i changes problem when there the application starts working differently when the user get something back from application that is not what they used to get so that we can update the help and of course there are some applications which don't this the their shoulder functionality to the user through the user interface X for example there sometimes hidden shortcuts which are mentioned anywhere but still also not good there so it was really help if when your body's so when we were documenting application just come talk to us tell us what we should be looking at that really helps of course as we document your application we will do a full user in a your i review and usability testing we will actually go for your application and we will try to use it as we normally what i tried to use of how other people like you said and the average we find ten or twenty bucks and they application give application what we do that even if nothing has changed in a few months so we will tested for you said do last customer help for it so the moments we are working on developer documentation and the platform overview effort is being but by for the tickle who is over here make sure gonna see it's a an area which has been neglected someone and this desperately need of more work we are restructuring the platform overview almost from scratch have we have new review pages and we will be integrating some of the developer documentation into it so we always we always need help with that so if you have to help that's just come find that's where having it at a i have has so on a for the help so we have implementation i sorry about the documentation that we're have this for next week and also the system administrator guide the guy the system illustrated right hasn't had much love sense before and it three so well to have our system administrators would want to manage their users has changed and the at the moment there is very little documentation about this there's something a few things on the we key so that's what the other every at that were currently focusing on and that there and there are who's doing that there are helping out with that huh and also we have been so busy making sure that all the application help as up to date that we have slightly neglected our startup guide the sell that this document which basically helps a newcomers to the docking station team learn how to right the hell which turned to use which vocabulary to use and grammar and turns all sorts but that's been a bit neglected because we in concentration on the user help so that something about we would like to get on some time soon as we are all those the almost then we have or specially writing these are help all of these are hope and mallard and almost all that's up to date now it's actually gotten to the point where it's quite difficult to find you projects for instance two documents so when i'm with you want to make sense from nothing to P just like to say a big thank you to brian and rate who have provided us with a lot of help and tech support when it came to the system administrator's guide they're the people who wrote the tools so we want the last for the help and they have been very receptive give us a lot of advice and that means that we've actually what we have pretty so far as accurate precise and it's easy to understand a question has proven to be a very basically the best developer to work with a typical what cindy here has support will start talking to him as she was writing the user help for the terminal and he was very receptive to improving the U R E and the basically he provided support when we do that and what station with of the top that's they has been very helpful that's a writing tech support that are happens which we have needed at the last happens we had three out of about eight laptops die on of in the first day that was fun under i that he's also be very patient with our intense and sneak comments as being great yes you have there are beyond a and same for a them adam has actually gone so far as to what for instance through submitting there will potential entrants for that speech problem three submitting the first batches and debugging their problems when trying to build applications that takes a lot of dedication so a big thank you to adam as well so having a few more talks at one thing about the conditions there is one later today i about by getting started videos which are what you see the first time you want to your user account your name user account so he's giving a presentation at six P M today i like i like talk i think and the pattern twisting right there it's going to be talking about what we've been doing with the developer documentation over the last two years market was an outreach program that one well you started you have your associates last year but that covers what is a tiffany started on before that and that's will eventually be integrated with the classroom overview which for that includes working on so martin stop it's the more at four if you're interested sorry that to them are to in this room if you're interested and developer documentation do problem that's what she has to say and then join us for the developer documentation had this next week so we're having a developer documentation well i'm sorry hard as for the whole week and we're also having a system administrator's guide had this for the whole week and all that we got the both with some international is a dish of people from that centralisation team will help us i hope make it's easier to write tell for translators well make it easier for translations to translate that help so that's i think that's all i've got to say for the last year you know the question i don't people have lots of questions awesome no use also to you want you know if you know use you should also i think that there are some companies that are using it instead of the but there aren't any major use out of it outside we have well she'll have spoken to katie to see they would use what if you could write something similar to yell it for them to use and for them to use my lights a friendly lot of the data help but i just five minutes i think i'm thinking so i have a question after every release what sort of testing goes like remote versus the tutorials and things like that make sure that they still work against this is that don prior to release or i mean we try to do all testing before the release but what if like me and i stuff so we are actually we didn't get the developer documentation testing done because we don't have that people to do that that's why save anyone's interest and all the documentation we really very needy so if i can help you with that i have i think this is some sort of this is a function of outreach your marketing team in which we can ask you can mediate march two i can people do that especially things like tutorials work that can that can easily be done the one is that you have to have image that we there could do test so that we can that least even or something provides an image prior to release and then actually so i would be really great if you could that once that actually happens and as far as i understand austria will help us actually do that that's thing once that what's because more mature and that's true for translations to translated documentation i think we buy documentation all the go always we don't have documentation freezes because we don't have enough people to actually be able to finish it sometime for free we might be for the could mean we might be a good so i thought should indicate how much spare time we have for testing but we do try to test and we do make sure that's what we actually might we get for if you saw problem within the team and of course if anyone else falls about we always say patches welcome if you want to help us what we fix it okay all right so i'll so we do it thanks for helping have like here i so you mention that so you have interns to do documentation i guess that is problem with documentation as much as with many other non cutting tasks the if you want to be sponsors low paid over there you want to call it to do any of this work the average for women is really the only thing that's available do you see that changing going for those of any chance of some money from elsewhere to get people plates right augmentation to be on is probably not because most people don't seem to care about age it's anything users that you we have another marketing i think i mean it would be i added that most of i need like and the dock station team has been found outreach program and half of our team it's female happens now which is very usual for and i suppose project have we have actually had who knew man train it is anything i think that i think it's becoming very out features and it and i would actually love to see new members join for not i think that bring a lot so about the fact that we say is that a lot of people do think documentation is important so from my perspective documentation is right now my number one focus i so comes out of this if you are trying to learn the platform are trying to try to do the code samples or things like that the documentation is this your only guide to actually writing and now and if you don't have to a let me give you an example so if you want to write a java script that everything is we have is just generated by you know G T K to or you know five O G attic introspection we don't if you don't there there's no context and start which you have nothing that says this is how you're right one in java script from you need a loop you know that you need to do they need to do that that's part of java script so if you're we can warrior and you only have time to do it like myself they're gonna be very frustrated very quickly and how we get pumped by other everybody else because are documentation is poor and we're expected to read the code i don't i don't want to read i wanna see documentation we also need more people we just want people to like that made one developers who are willing to write that station or just people but it's not good so for me as a brand it affects the right so and that's how i look at i happens that that's the number of people who have been looking for documentation well what occupation right and their application i have actually just coupled for and they found out there helpless way which isn't ideal we of course always you want to provide documentation but unless we actually have more manpower to do it i don't think it who is like we do have me back to see if there is obviously working on the development innovation we've done some what we have a have a lot more where we are finished first you know the structure of structural thing you about the documentation we just need for they okay she's where is the still when i was doing the outreach program from and a internship i fell a lack of documentation to do right documentation that's what the style guide this for still i so i dutifully went and looked up the style i like to write out of print and you know slapped on it but i don't at and i didn't hear commence interviews that is outdated and so you have in place a style guide that you recommend to read and it is outdated so my question is why are two guys working here because we've got too much today what i don't know hire right now we had solved on the last year and then we don't have anyone interested enough to do it i was actually going to right that's myself four months ago i think but then some other projects came up and i but i hope for the since that so for example i chose to write that this me helps the writing style guide it's just that we don't as i each individual the T basically a team works as individuals rather than the whole team unless where it had passed in which case we just put all are written to one thing and we go out that i will get done is jennings and to work on what interests ourselves rather than what interest what specific people might want it was we take requests and that's why we fix but we still say twelve about we will fix them still the cheapest i described widgets right me basically how you can what object is and how you describe it in your documentation and seems with a the release of G D get to be in you know on the applications using a the new G T K tree lot so we just have changed and those do you don't need a you know a G D B which is not right and she and how are newcomers to see educations only great and you get supposed to describe this generally we recommend that they be at the moment like i just finished that if you know and we recommend that they be that if you know because that's actually a good example what help should like and describe based on that but there's where using for them three applications are still somewhat flocks for example empathy was are flagship document the project three years ago now that is somewhat outdated because we have actually able are the style of motivation has a fall down through this i think it has improve we had fewer what we took into account the feedback from users based on what they found confusing and so i would and that will keep evolving process evolving for some time to come but it's at the moment we on our project patient the what can we say which is our application to look at four and user help for developer documentation we don't have a specific style guide at all because that is still being developed and the if you actually go read was already there but that's not to the full so i've just one ones so at the data that a still by the time for women and when i it you have a language that is why it's not you know what is going on with the documentation team and what is a place that i list doesn't have any of this stuff that you're working on i mean you know what is propose the system admin guy that the guy and usually there's you could very a quest for the system administrator right there is a purpose for that well right there are a separate pages from the application help there three cost less and then there are links to sell it to the documentation could perhaps that G D V saturday included in the tasks for the thousand the page it okay cool i'll okay so two things one sort of report to your home and one about trees so it's not the it's just something to help your rights documentation if you use emacs emacs is really good for everything X M L based documentation and i started a little project called you know emacs you kills it's my blog it's basically you download at it's model you are installed you tell emacs about it has a condition have to do that i mean what it does is basically every time you open a model are documents in emacs it's kind of the model are X M L schema and you have tab completion for the available tax at any point in in your document so you know if you are inside of that patience have a section inside of paragraph people tell you a key right here you can put you know all emphases or a reference to another thing more linked another it is very nice it's very useful so we need style but we definitely nist i would i well you know when i started writing documentation a that was when we used a cool and the hope is this immense ocean of tax and emacs really help me there at least you know what i could do at any point in time or at any point in the document and you know i had for that specific case you know that will pass like i don't know nine different types of lists one aside my fleece order these variable least list of this and that kind of thing and even if you get it wrong the first time once you have the content in their it is really easy to change the least i and the sub element types to something else you know so don't be afraid of using the wrong elements type because someone later look at it and say you know you should be using this one instead and it's really change but it's getting the content written but these hard part just in response to send it's actually very similar with my learns you have for example steps for lists which i think steps and the lists we just for the list of items terms for the vision turns and that's what's in a similar way and the point the whole point so well how to hold a part of the point of using mallard was the tax should be relatively self expiring three so as you type it as you write something you should be based on to get some steps and get some steps and steps why want to show an example and then you just use an example tag and this is all fine i mean but that's not personally not only concern what i'm saying it's a i I G some kinder now and i am i've done some small features for this that gets clients "'cause" but and down they are they're using a lot of me which it some G T K tree and i had that i never seen them before i mean these they're very new show there is like G D G T K had of are now i have for someone who is waiting documentation for this like let's look let's go back and look from and you'll be point of view of how will how will they describe our how will they know what's ahead of our do they maybe that person thinks okay this is the top but are is not think of the same thing i had to the developer documentation actually requires prior there is that we have it you have to know what you're describing so you have to actually develop the call that were or what about right you should vision for you i mean you really so that's where most are still have a little overview a whole different parts from this thank you or would have time to recruit these or both kinds of things and then we can start looking for from that we get this is a some advices ripping right there is a cell phones and also and they what's to say something so file i guess say what's missing something also start let's about is it is a problem recently if you're interested will actually go for the presentation about something you would sort of in detail but reputations and of course all these things which recovering so if you could to discuss redevelopment vision that which recovery you will see this thing so that even visually created an idea some of the new features that you might want to be looking at but at some things that you know somebody we started documentation now we don't know the documentation is supposed to be we have low entry barrier and you're taking people who don't have a fourteen experience so it's like a chicken any problem you want to know that of the documentation exist that these are like really new people so they don't hope for salvation is not really intended for self is that you maybe you have to know what they're doing show it is it is a requirement that you need to specify probably a on the page before you know people line we have people contributing not very good outreach program and we actually there is really have very many what with this year we have a have a and that's what about the documentation we had that we currently out there for the user helping you to use a help as well last year we had four and there is for developer documentation they to start from scratch so i think it's to them along a lot of time to get up to speed i have martin can probably say something about that if some parts her microphone i am working i'm trying to work on that on something that you might like it's the it's a you something can there is the door you know so far it's just for dig a i would like to have something like that to for other libraries the i'm working on the one for by then mad for the market is upstairs because we i might for the is working on something similar for javascript and actually my talk tomorrow about this project so i are you getting to be talking about how you actually started right to help us and you come right yes issue becoming that's good that's good for me irina and i think sites also have on site okay i just i something what's in the say as and things that need of more documentation on the B P a one of things that i have some but depending on but then one of these is to do with experiments you i am hoping that should i wouldn't want in here don't getting that we use because i as well you know some stuff one experiment you i interviewed use but i think it's more to do it the fact that they're not i don't we're going to be because i had like use experiment us but mine as for one of the but then it still don't know how to and i couldn't really find documented and you know stuff on the big on this or maybe i haven't been can probably well if it's not there thank you can out that it should actually right that the patient i'm you know i'm just seen that i might don't know how to experiment un in i okay so for start but it's not that we key we did not have any documentation about that the location for that is on the project about website and there is some degradation about that but it's still okay by than a space it's really as experimental we don't know which way will get better does a lot of work with that so personally i find of the best thing to do is actually look at examples of that this work different how to use it i think it does but have you have anything to say that's about so but it's sure it's course for books about most experiments this is and all that this implement that we will go or it's a moving target also changing we maybe have also you know sledge my lower the biggest visual know ricky which are realists men's from the experiment on them snakes basis that i want to implement the you know so that's probably the only resource new one more workable we have us just a quick comments what on one know the your slides there is a library but know that and i think it changed to help that know that all know that is actually not the case lightly cover is held about sitting so when you get like we the first thing you see is a user is developers system straight i want to actually click on this is will take the something but actually like that what websites we get from that covers all of have to use it developer and this is a straight guy we have some time for some more questions anybody so that so i mean we king mo P flow what's your strategy for the next so i don't know speaks something like that and it does seem like a lot of stuff found it's not clear to me and what is most important to be like we do not have a very diverse team and as i was saying most of us prefer to work on user help because that's a lot of about to have very few developers and the documentation team which has proven to be a problem but generally people working there is that they're interested because that's where they must matrix to work so i hope so for most the contributors i expect will be working on maintaining the user help for they could is leading that right for the developer hell that that's our entire happy working on the system administrator but i plan to continue working on that we have brian voices well who has been working who has started that how do i series of the week E and all that's actually just one of these different things if we were to constraint on one for start it would not be good use of our time because some of us do not are not very good in that area of course we can amend have to but that would just me that we would have to give up working in other areas to be able to achieve okay so no my question online and so what's your strategy and for the better no what's your strategy D to have like a set a so plan come a because it i if it can be difficult i think for people to you can vote still didn't know you know how to how to style and i think i think i this is all the goal currently for the developer who is to finish then you buy from a fee which the go for developer help is to finish the platform of review which is which is and gets so anyone can go look that where we are i thing you descriptions for various areas of about form i swear moving the we're moving the that is that's what has be working on into that i once that's complete that will be development or so where overhauling about from scratch we have i know for the user how it's now getting to the point where it's primarily made sense if you go on to our we key which you will find so we got a little functions documentation project and that youtube application helped us page you will see all the application help supplement english that there and it actually has individual states this our aim is to get all of the states as into green which is complete done for if you and ready to be shipped and that is basically are ongoing maintenance we have i mean this now finishing the last all day user help which experience of from the top block as far protection any other questions i think we can take another question anybody is just a couple of minutes left okay thank you