Still waiting for someone else to do it: Writing documentation for an open source project

Video thumbnail (Frame 0) Video thumbnail (Frame 862) Video thumbnail (Frame 1365) Video thumbnail (Frame 2009) Video thumbnail (Frame 2776) Video thumbnail (Frame 3327) Video thumbnail (Frame 6516) Video thumbnail (Frame 8023) Video thumbnail (Frame 9162) Video thumbnail (Frame 24100) Video thumbnail (Frame 24864) Video thumbnail (Frame 32579) Video thumbnail (Frame 33045)
Video in TIB AV-Portal: Still waiting for someone else to do it: Writing documentation for an open source project

Formal Metadata

Still waiting for someone else to do it: Writing documentation for an open source project
Title of Series
Part Number
Number of Parts
CC Attribution 3.0 Germany:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Release Date
Production Place

Content Metadata

Subject Area
Many people will cite how their adoption of software was based on the quality of its documentation. At the same time, documentation can be one of the largest gaps in quality with an open source project. This talk will discuss why that is, what you (yes you) can do about it, and how the author has (so far) managed to avoid burnout by learning to (grudgingly) accept less-than-perfect grammar. Examples will include things done well and lessons learned, as well as humorous and painful failures, specifically from within the GeoServer community, where the author has lots of (perhaps too much) experience.
Keywords Boundless

Related Material

Word Computer animation
Supremum Metropolitan area network Execution unit Computer animation Open source Perpetual motion Projective plane Maxima and minima Convex hull Number
Bus (computing)
Boss Corporation Computer animation Multiplication sign Workstation <Musikinstrument> Bus (computing) Cuboid Device driver Traffic reporting Writing
Standard deviation Open source Mapping Multiplication sign Projective plane Insertion loss Power (physics) Number Revision control Frequency Computer animation Software Insertion loss Computer configuration Hypermedia Software Videoconferencing Energy level Videoconferencing
Point (geometry) Logical constant Touchscreen Open source Computer-generated imagery Projective plane Content (media) Stack (abstract data type) Code Shareware Revision control Medical imaging Exterior algebra Process (computing) Computer animation Personal digital assistant Website Object (grammar) Information security
Complex (psychology) Group action Source code Wiki Blog Insertion loss Different (Kate Ryan album) Set (mathematics) Social class Physical system Metropolitan area network Computer icon Touchscreen Software developer Web page Interior (topology) Bit Zeitdilatation Unit testing Formal language Product (business) Arithmetic mean Process (computing) Order (biology) Software framework Arrow of time Text editor Writing Probability density function Point (geometry) Inheritance (object-oriented programming) Open source Computer file Computer-generated imagery Maxima and minima Similarity (geometry) Control flow Device driver Online help Event horizon Number Dew point Goodness of fit Inclusion map Googol Hierarchy Data structure Text editor Metropolitan area network Data type World Wide Web Consortium Scaling (geometry) Information Frustration Server (computing) Direction (geometry) Content (media) Code Counting Volume (thermodynamics) Line (geometry) Directory service Limit (category theory) Web browser Word Integrated development environment Software Design by contract Social class Touchscreen Greatest element Code Direction (geometry) Multiplication sign Function (mathematics) Mereology Computer Formal language Word Mathematics Bus (computing) Endliche Modelltheorie Extension (kinesiology) Position operator Probability density function Source code File format Computer file Point (geometry) Open source Markup language Term (mathematics) Open set Type theory Textsystem Repository (publishing) Software testing Right angle Energy level Procedural programming Resultant Reverse engineering Server (computing) Vapor barrier Link (knot theory) Software developer Web browser Content (media) Wave packet Revision control Navigation Integrated development environment Software testing Summierbarkeit Online help Projective plane Java applet Software maintenance Wiki Computer animation Intrusion detection system Blog Formal grammar Object (grammar) Electronic visual display Extension (kinesiology)
Server (computing) Open source Link (knot theory) INTEGRAL Multiplication sign Source code Electronic program guide 1 (number) Translation (relic) Mereology Perspective (visual) Proper map Number Formal language Mathematics String (computer science) Forest Maschinelle Übersetzung Distributed computing Information security Position operator Condition number Area Multiplication Email Forcing (mathematics) Projective plane Electronic mailing list Sound effect Binary file Word Computer animation Integrated development environment Uniformer Raum Quicksort Whiteboard Object (grammar) Arithmetic progression
Computer animation Software repository Multiplication sign
Computer animation Open source Projective plane Reading (process)
OK thank you run for being here and and and some of them require working at Nigeria's and be after the session and please welcome our 1st the amide from trade wording for 1 last week uh we talked to us about the challenge of writing good documentation and the involve different both please thank you to so when he was like
country and I've been involved in documentation on that user project for a number of years long some others and you talk about writing documentation for open source
project so we'll start here yes the the 1st this it's a
really outside Salerno Italy and many years ago my friend and I were backpacking around Europe and we would to see these ruins and we took a bus
there from town and my friend left his wallet on the box and so was very distraught the next day we went to the police station and write reports and I've actually while he was at the police station I went back to the boss the same bus station that we took the bus from at the exact same time and he the talent the bus driver my friend lost as well as all along how I this I know 0 Italian so I look at my phrase book and I have no time to figure this out the bus arrives and I come up with this for if
you know Italian please don't last because
it means to lose wallet yesterday it was the best I can do you might be asking what does this have to do with documentation for an open source project will return to that question later fear with me so some of the
challenge here he worked on open source projects the about if someone spends 30 thousand dollars on software there have a lot of investment in the learning how it works you might spend a very long time trying to get it working in under standard and evaluating it but when they just downloaded something like many open source projects you just download it how long are they going to take before they either have successfully give up will Quinn or move on and they don't get a quick wins that is the challenge so documentation priorities if you're just looking at the high level there 2 big priorities number 1 you need to tell them how to install the software you cannot assume that this is something that is going to be easy number 2 media with win Windsor people sailing I've got this offer and I see a thing so work on the Jews of a project so what's our our frequency in their data on a map induced we everything else is subservient to that if you don't get to those 2 steps it doesn't matter anything else you write about because they will be reading they will have moved on to something else now so installation is used as a sanity check to tell things OK do 1 step at a time don't waste time explaining other options remember at all times your software is being evaluated this is not the power user stage this is the if it doesn't work I'm gonna go buy something else you download something out videos are great but they tend to be a little difficulty gives you a sense of hope someone did someone not installed and the and I can be the only persons had trouble just getting the software working this is why I spend so much time on version videos are difficult because they go out of date and so generally speaking I don't recommend video so much for the installation save that for the cool features that the software exhibits once people have gotten them and stopped so the quick QuickWin called the start little Miss named because well
it shouldn't be using this it should be quick it's not always quick with the objective is to go from just insulted something on the screen that's awesome so that's the 2nd step you do 1 thing you do the other what other places that people get caught up in the that exchange but we only documentation we have stackexchange establishes this don't security site but 3 popular with user aren't you told users is kind of like an alternative to usually less but is not documentation it however can be used as documentation supplement in the sense of question that asked repeatedly they point a whole at 0 people are always asking about this maybe we should write it so when you're working on open source documentation you look at a project 1 thing that I have found that is always an issue is curation duration is difficult to give an example of that
and having people familiar reduce keeping content from getting stale and out of date is a literally never ending process every version something goes out of date and so it is a constant struggle case in point I was a GeoServer codes break in January and I found this general this is great this is it was an image that was in our documentation this is from just 1 . 7 which was released in the womb before 2009 and it was the end of the year it was in our documentation as of 2016 itself 1st they can learn is that what I'm speaking up here I'm not the example that we always have to model you're doing our best but there's always room for improvement so curation is difficult duration is also slow
of last year the jury got got my colleague a version of this talk at last year's faster gene and mentioned how there was a new feature the user which is the you geofence security system due events has a URI and said look look at our documentation we don't have any stats and that he report this year we actually do have something so duration is slow but it does happen but it doesn't always happen for example last year curiosity talked about the fact that this complex feature example this isn't due tools didn't have a code example and unfortunately I just check last nite and no 1 submitted anything just yet so this is a problem so maintenance and you have a to be the 1st thing together like for example features get dropped and the documentation documentation can stay we have some stuff in there that was over features taken out but no 1 was involved so sometimes what happens is that the code gets produced as done we got paid her race but then if there wasn't any facility for documentation and then will get to it later and we know when later is later is never so what GeoServer originally had a for its documentation anyone can edit the problem is is that you know dew servers not Wikipedia we don't have this critical mass of people who were saying like I am knowledgeable about a certain things but not knowledgeable of motivated enough to make wide scale changes your community cannot do all the work for you he worked on a project there's certain things that you need to be able to be proactive about so we actually ended up ditching the the which because it was actually working for us and we try to create a more structured environment so I'll tell you about that as well the important thing is that when a project you can have the community to work for you but you need a gatekeeper were curious someone to say OK that's the work you've done now I'm going to put it in position on going to approve it just like you would with code so this is something that we adopted about of feature is not done that completed until it's documents I would say we're pretty good about this is kind of model even developers know it now they say like that's done by our 2 D documentation is kind unit test it's something that you need to do is part of the process it's not done otherwise so what i was 100 % successful this but everyone knows it and rebuilding in time we build in time contracts and the work we we did so I am not a developer a lot of the things that I write about I only I tied to understand it a few days before I wrote it so when I found that works these 2 things number 1 if I can get a developer that worked on a project to worked feature to this right some limited information just really Rostock and then I can translate that because I have the experience about writing it and putting things in order and doing this for a number of years of NFL networks is that I interviewed developer you get your curator to interview the development silicate what is this doing what I like and that usually allows me enough information to be able to write something from the so for example another way to get documentation to happen is that you included as partners offer policy so GeoServer has extensions official extensions and in order to be approved for inclusion in the project it requires documentation and test you want and you have to document and as a result the documentation for the extensions now include of much their job over document the new features so it is it conducive originally before I'm involved a couple years now but originally was actually just raw HTML and you know about that but some told me that but there was moved to the wiki and likes wiki didn't work and then we decided to do is that documentation has the same types of issues that code there are versions there versions and there are features that are associated with them and we want to know who did what and so we basically decided that we wanted documentation to not live outside and some wiki in some other systems or word processor or what have you is that documentation is really cult so we decided to put the documentation in the code but so training doctors code allowed us to do a lot of neat things so if you're curious we have for many years now a documentation generator called Sphinx and it was originally designed for Python the output but it can can basically do anything it's reversal of the nice thing is that it builds documentation from a structured text format and it can build it in many different formats HTML PDF and LaTeX and some other formats so you you write it once and you can generate it in a lot of different formats the structured text is actually known as reStructuredText it's similar to mark down like this you know title and subtitle and there's a link in there but it's a new kind of like a rich text so that is a marked down it's similar to I think that stands out is that because the documentation is treated as code they're right next to each other in the directory hierarchy of the the repository so things allows us to actually included code in the documentation is the there's little include literal included the bottom so that is actually pulling in the source code so if the source code changes the documentation never goes out of date 1 last thing to have to keep up so when we took away the wiki a alas people still want to contribute Some people do doing they're very motivated and we want those people we want to support those people we don't wanna give them too many barriers to helping the project so that now that we have the documentation in code we can utilize the same types of procedures that others get hung software projects have that anyone can edit just simple steps you go to the documentation is right to get up repository and you have allows you to edit files directly so anyone can do this you need to have a good habit counts but you don't need to have commit access so we have limited the barrier to entry so that all you need is a good habitat in the file you know if you find a typo on a fixed that typo I was 1 fixed typos that's my and that's how I got into this gig step 3 you just use the built-in editor you don't need to install sphinx you don't need to install python you need to install anything you can just say like I found a little bit of a table or 1 at this thing in and then you modify the file step 4 you could submit and then if you don't have to access like most people don't then a pull request is created gets sent to the developer team gets sent to me and then we evaluated and we either make the changes in that same hey this break something but either way the person has done the work and contributed writing tips request never CdSe where line is not easy if the what were easy then you would need to you because they would have figured out and they would be reading your documentation but similar similar never see simple or simply because you're gonna make users feel stupid if they can figure it out like just simply a matter of no it's not a simple it's always easy when you know how to do it from Strunk and White be concise omit needless words simpler more concise no scrolling through large volumes of text we only hear your opinions you write a blog similarly no market great cool easy way to do Austin things they know it's also they're gonna figured out of your software is awesome they will know be professionals don't use slang some people are coming from a language that's different from the language that you're writing you know it's a bit when you're learning a different language the last thing you learn is you work this it's the nuances of the language the objects of the same character web browser and pointed in the direction of some people who don't have that command of English appealing fire up what it doesn't help finally assume longevity if you do something chances are it might be around for a very long time because we have a limited group of people to do the work right now especially when you're starting out things may not be so assume that you're writing for the future assume that you can be as generic as possible I like to what I do screenshots cut out anything that makes it obvious that it's a specific version of because that way when the next version comes out all of screen shots have gone out of date see do a little bit of work now so that you can do less work later finally this you take nothing away from this remember that the phrase is not don't let perfect be the enemy of the good phrases don't let go and be the enemy of nothing your goal if you're part of an open source project is to elicit content for the documentation but you don't need to require beautiful world class elegant content you just need something something is better than nothing now as a grammar and I have a lot of trouble with this because people submit things and and I just I wanted all the correct and bad grammar makes me twitch and and it's just a misspelling stick out to me like nails and so that's the challenge this but I Stephen
lines that the point of words is to communicate information and as the philosopher Troncy said words exist because of meaning once you've got you can forget the words so where can I find a man who's forgotten words like and have a word with him so during that most of I went and I said this broken Italian phrase to the bus driver a good idea
to have my friends somewhere in there I think there's a lot thanks the
security and so now we have time like 7 minutes for questions so integration the rooms to create original thank you of and so when you brought up perspective change this I was in part a good idea to go back the other way so once you've found this is something which document as people keep asking about it you might wanna go back to those questions and create an answer that points to the new documentation ones that exist so that people can find it's a good idea or the Agassiz better than hoping that know google searches pick it up but yeah and that's the way you give people will be finding it on exchange what's the question exists so you if I want a link to it that way as well to think about going to have to round trip some people are not going there that feeling that was really the effect of area the reason to that my books have installed on an automatic distribution system for the documentation so it find some marketing and use force and when multi sited finds 1 marketing boards so some users forests really like this and so on and so will automatically tries to world uniform object positions writers the book I like that I like that a lot we have produced we have a style guide so people can read you know the good things to do in the bad things to do but definite automated i'd have love the idea that the but the question and at the end of uh screenshots the you have any other way that we to reprocess screenshots once in a while or do you render them many the every time we need that in the documentation the screenshots of the different areas of the you uh uh redo the screenshots manually every time or do you have a that the made that way too create them well we don't normally create the release of the tools that we use but what I always recommend to use when you create screenshots to create as tight and cropped a screenshot as possible so don't see the entire thing to show only what you need to show therefore it minimizes the amount of potential particularly dates 2 and there was a question this so I'm just I'm interested in translation as well they do we have any experience or any tips like to set up a proper translation systems often really of Transifex and scooped up so not as part of the documentation for saving GeoServer server for the actual strings in the UI but and that sort of that area we do use trans effects and we have a number of languages that that set up or we don't really have a facility for automatic translation of the the raw documentation itself that's kind of I mean I think there are there's a lot of work in an environment in that area but I think auto translation of of words is not yeah its claim it's a challenge so we have relied in the past on people who wanted to make translations to actually make the translations themselves on the progression so so maybe yes question what do you think would be the like the best way to start contributing to the usual sort the condition so for anyone who is interested in contributing to the GeoServer documentation easiest thing to do is I would recommend join the mailing list and getting involved that way we have usury users mailing list you can download you can look at the source code there and read the documentation of documentation online and but I think if you can read what we have I think if there's something that sticks out and says I wish it said this or I wish it did this I think usually you figure it out pretty quickly what you were when you are likely to want to do so that would involve justification for using usually you using Sphinx from of alternating open source 1 for augmentation of with us in the most of the projects use just destroyed by conditional but are there any object is that you are evaluated or I I'm familiar some sometimes I've heard that make docs and get off another 1 of things we use the documentation generator and there's a few of them out there but that's really what I've heard recently so a lot of times they're not even really using so much of the documentation generate a lot of
times they are using markdown
down and keeping in the github repo into the principle but thank you and the question was no I think you might think you and the
few hopefully you user generated than there is in its reading in any open source project documentation