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