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 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