Merken

Everybody wants (someone else to do) it: Writing documentation for open source software

Zitierlink des Filmsegments
Embed Code

Automatisierte Medienanalyse

Beta
Erkannte Entitäten
Sprachtranskript
been get off that easily so I have a question for you what
is exactly innovative about writing documentation for open source projects but the good Felson and it is because 20 minutes ago if analysis of of indigo so welcome to the last afternoon of phosphor G before we start the glorious codes French tomorrow but today I'm good presented talk but that's actually not my talk of this talk is
put together by Michael palm free he's our community advocate that boundless and by that I mean that he's really producer that he helps chain the wily developer he beat English sentences out of them and helps at act as a buffer or a translator between down all the technical stuff that goes on in real people that just wanna get stuff done so Michael pump freeze a really nice man he's unfortunately not here so you have me um the this is kind of what I look like uh I kind of like a abandoned in this picture because I'm in Philadelphia coast code spent itself it's rather cold outside so long and and run I work on a number of projects tools and induce urban uh also work with the Eclipse Foundation location Tech and also the Austria foundation so just in terms of getting started here this 1 give us a rough clue what we're up to up against his as sulfur project if you had spent 30 thousand dollars on a softer project you might spend a week learning it you might take a training course you kinder-care little bit if you spend 0 dollars an open source project how much time are you going to spend 5 minutes 10 minutes 15 minutes but you you really need to focus on people that are downloaded and are trying out our software we really need them to see visual results right away or they're going to go on to the next project so we've got really stiff competition but in the open source world but in terms of documentation priorities I just like you that perspective in mind I really wanna focus just as a matter of life and death uh of an open source project on making installation using and so we really want ensure potential users can actually install your software I know it sounds like it would be obvious but it's a it's a turtle but a lot of projects stumble over but the other thing we wanna do some kind start I wanna make sure that users can install the software and see their own data in there is a lovely project that that the Open Source Geospatial Foundation is put together in order to help with both of these aspects called the August you live DVD it's not actually a live DVD anymore as its little USB stick saying it so it still alive now that a USB includes a lot of open source software installed and ready to go and it crucially provides quick start so that you can follow to see these projects on screen and just to go over what we want of installation we really want to get the software installed we wanna show each step we must show a picture of each page of your installation wizard of people are really going to be doing a comparison between your instructions and what they're saying on their own screen because they're desperately nervous they can do something wrong and it's really a sanity check to make sure things are going OK the other thing that's really difficult it yourself developers please don't get distracted explaining all the wonderful options that probably only 1 or 2 people in the world care about and just focus on getting the software installed the water to people that can come and talk to you later well 1 thing I've seen recently is the is installation videos who here's like what's going to install PostGIS video or something like that on any 1 couple people so they're very friendly and people get to hear your voice and and follow along on screen but it's it is because it actually shows the software working so that can provide a sense for this a couple things to keep in mind that it can be really hard to find an installation video that matches the version of the software you're using it to also be really hard to follow the steps that have been taken into up scrubbing the video back and forth and it can be very frustrated so I do recommend using video to like showcase new features and so forth but please do stick to documentation for our installation instructions but in terms of a quick-start were really look once again looking to show rather than tell so we're going to try and focus on the key value out of your software so for GeoServer we really want to get to your server on-screen and show it off being a web map service not too many people interested in WPS web coverage services or how to configure the latest performance options and we really just want to get the project on screen and show how it's amazing but another thing people run into is the dreaded stackexchange this is where we all in high and how he has been very a responsible member of our community lurking on Stack Exchange and helping answering people's questions it's a little bit of a question and answer site now this is more of an alternative to a user in reanalysed than it is to documentation so it's really good at helping answer questions again asked repeatedly on the user list but once again it can be hard to be working with an older version of tools are an older version of GeoServer to hunt down at exactly what you need to do so just in terms of writing tips and tricks and I just want once again remind everyone that the slides from my country so I'm part of the problem he's trying to warn against in terms of these writing tips and tricks absolutely terrible spelling and I depend on people like Mike to clean things up in the 1st step I wanna do is when you're writing instructions please don't use the word easy the only thing that can happen here is that users feel frustrated because it's not easy it might have been easy when you wrote the software that 2 years ago the chances are you're writing for the future of maybe be referring to the start menu and start many was bombed in Windows 8 or maybe yeah that talking about the windows ordinal start screen and then also the start is back in 2004 I think in the next 1 here we know stand so just please don't use the word easy it can only serve to frustrate people the other word to be careful of is as simple as simple as but a lot of people are coming at geospatial and software with different backgrounds to something that is simple for you might not be simple for everyone else there on the internet and so the only thing that can happen here is you can make things make people feel stupid if they don't understand something you're describing a simple and to just 1 piece of software on its own uh is pretty complex once you start putting these pieces of software together it gets more and more complex and sometimes we will be using the software you in the future an operating system you've never heard of so yeah just keep in mind stay away from these words now with that in mind and maybe a little bit meaning to the GeoTools GeoServer community to his sanity check how a steel tools do we found 46 uh cases where summoned use the word easy in GeoServer we found 40 and firm and boundless OpenGeo Suite within a little bit better at 19 Our in terms of checking for simple were doing a lot worse so for GeoTools were getting over 100 same producer and same for OpenGeo Suite now in our defense that the OGC has defined something called Simple Features for SQL or simple features and so a lot of these hits are false positives and so I'm going to have to cut the team a little bit of slack then I wanna do is that when you're thinking about writing and focus on getting any content at all from your developer community so dull we've all heard about don't let perfect be the enemy of the good in the open-source world I wanna soften and they don't let good beta-band the and the the enemy of nothing so often if you complain or or hostile people too much they they might walk away so really focus on getting any content at all and would be a good thing and we also have to relax a little bit about things like grammar and this is once again Michael Humphrey talking either lacks about grammar a long time ago and I just talk a little bit about maturation of content both tools induced over a very long lived projects like how when you tools stock 1996 something like that and you tools in version 1 actually and died due to lack of documentation the developers found that they were spending so much time to answer user questions that they don't have time to actually fix the box so we did the only thing possible they fired the user list uh and started tools to so so here's just an example of what we're looking at in terms of creation this is a page in the GeoServer 2 . 7 talks about the GUE
XT-style this is a feature that hasn't existed in induces for how many years to server 1 at least right yeah like so I deleted this a couple weeks ago and here is 1 of the latest features of GeoServer without this wonderful security model called you friends and there's no talks about the going down so we got some work to do and here's another interesting 1 here for complex features that the opposite of simple features and you can see that after many years of being a popular a part of the library but there's still no example code for a new developers to certainly have worked to so how did this happen they can be very easy to come to forget on that slide some of the maintenance work involved in projects documentation and quality assurance can really be some of the 1st to go up for projects that have been going along time often developers hope to get back to something but but often without each champion such as that you XT-style and the feature can be removed and no 1 spot to chapter and clean up the documentation the other thing that happens especially in our modern kind of commercial open-source world is that the features that produced under contract so they can be a great it's a bit a social pressure to get a new feature in so that a development team can get paid but we actually risks development team moving on to the next the next bit of work and then hoping or assuming a volunteer will eventually get to it so we've got a real tension there are 1 of the things that did not work for us is using a wiki so using a wiki was something we tried in 2004 so in the hope was that our user community to help us right docs so do tools had to give up on using wiki I found that after acting as editor for a lot actually written 90 % of the wiki so so-called examples especially were really out of date and the library was getting a bad reputation but because the examples were hard to follow in people's in the library was hard to use and introduce over the OpenGeo therefore wondered about list and mandated or migrated to a fresh set of docs they did a complete rewrite rather than start with the wiki as 1 of their and don't know initiatives when they set up OpenGeo Suite so what has worked at policy the policy and this is especially important when we do professional services work the feature is not done until it's documented and I really encourage other organizations working with open source to take this attitude but in terms of what Mike spell his work he asks developers to write lol out kind of low-level adults and might translates this for the world to understand the other thing is done on occasion is interview developers to ask them about a feature and then from that interview he can write out the documentation now on 1 of the people that my could be interviewing I found that including the cost up front image you tools proposal so well we have a little section where you write down the scope of work and I make sure to include the documentation and you way as part of Ebsco work and the other thing I do is a volunteer is when a features likely to get cut were not included I might step forward and write a couple of paragraphs of documentation just so the functionality gets us 1 thing we've done is a policy change induced over is so now to get included in the project documentation and QA test coverage is now a requirement so this really enforces the idea that the consultants wanna get paid to have to provide docs of so we've had to have some seeing some success in this so docks and a much better job of documenting new features and consultants do know what's required up front but this is a barrier to kind of the casual drive-by get have gotten it practice that people often bought we ask them to write docs now due the documentation was originally written in HTML we did migrated from HTML to a wiki and so a bit of community outreach attempt but gradually this became out of date and as I said OpenGeo moved from a wiki into having the docks version with the code base and this has really been helpful because the version of dorks gets released every time the code gets released so people can find the talks that match what the using and the other thing that's happened is Thomas's volunteered my culture that might act as an editor in terms of tools it actually started in DocBook of all things which is like a terrible XML things but we moved to the courthouse wiki and as I said after a number of years and found written most of the Wiki and then the other thing that happened to us is vandalism so wikis vary from from the vandalism and that's just because it's the internet and we can't have nice things but so we've moved the code into the codebase much like GeoServer it's a little bit harder for community volunteers to help out with all show you how we can do that a that and the benefit is it's now in versions along side with the code and also we can include life code examples which is really nice but in terms of the non effort it took it took about half an hour couple days it can dock to convert the material and then about 6 months to clean up the mess so this 1 of my bigger volunteer projects so we use a a tool chain called and thinks so in order to install to work on docks you install python and then this is easy install python uh using installed Spinks command line and then you can run them make paradox and this is kind of where docs look like they look like text files that have been formatted so it is uh a wiki format and rich structured text and the killer of feature for GeoTools here is the ability to include live code examples that don't go out of date in terms of how the help casually it a part of data docs in case you see a type of you can browse to the code directly on get help and you can find the file that you want and it and there's a little edit pattern and you can make the change directly in the file and then nations scroll to the bottom and and provide a little commit message and I'll be sent to the development team is a pull request and get review by probably by Mike I would do that as a alive example but I'll keep keep motoring in terms of writing guidelines to serve a little bit more formal than I'm used to they actually have a writing guidelines so this really helps the community provide a consistent voice the writing documentation it also allows us Mike as an editor the fair and consistent when he's reviewing documentation and we found that often developers don't understand all of michael's fancy English grammar words so we've I've really lean on his good and bad examples and so 1 of the things we do try to do is be concise so we don't want developers providing a brain dump of everything they've ever thought of reference materials we wanna be shortened scannable as people are usually just looking for a few specifics of facts tutorials can be longer as you'd imagine often we find developers like to have an opinion we are happy for them to have an opinion but we 1 in a blog post not in our documentation the other thing is to even though people really excited about the work we don't wanna hear the excitement when they're describing the future if they wanted to to showcase the marketing then please write a blog posts so here is a bad example to overlays are a great way to publish supercool datasets awesomely into words and that's a little bit over the top instead we wanna take a technical angle but if there is something positive to say super-low overlays allow you to efficiently publish data by Google so will try to avoid the use of slang slang differs across the world and you have to be very opaque especially if you're coming as English as a 2nd language to understand what people are referring to and we try to be very succinct and professional in our communication we also try to provide direct commands and you know so rather than say a little bit backward now let's have a shape followed by 4 images be very direct had a shape file but we also follow Wikipedia naming conventions I don't mind what naming conventions used as long as you're consistent GeoServer is also an international applications so we make use of a facility called trans effects that for translations and this is a website we can log in and grab the the text files out of GeoServer and start to translate any questions on
that and we don't pretty with uh
few so 1 must have a question for a for a
story of documentation of wasted the time 1 it was to be images right know what I wanted to ask you track somehow
what's document own master have some kind of a man or our code for friends and for the test cases this this of code coverage metric that you can say OK my of this this car Mike Wald or not they have something wonderful documentation that's you know what's the commands of and what's not and what's so document next so we don't
have that we got a bug tracker and so we use that to find holes in our docs so it's something we depend on a user community for but I was talking to someone from that you just project earlier and they've taken the stance of having their documentation right next to the source code in the source tree so the feature gets deleted the documentation and it's deleted at the same time and but we don't have any kind of fail-safe like that and use the dual tools it is probably a good idea thank you that you may be brushed up pretty fast and yet the code block in the reStructuredText leisure again you had a all sample
certainly of the yeah really OS-ELM pretty code walking in research projects for many a library on that and how it visualizes the reStructuredText is quite common the world thinks distance in which
time I got which some through 2 minutes OK I haven't done this old talk at
all times when it quickly trying to an example yeah the because whenever you type applied at something out it's kind
of terrible people can't see it so here's our GeoTools docs here's our fabulous quick start tutorial if I can find it
can anyone read that at all a little bit so here
we've got a little thing we're saying literal including OK artifacts eclipse any so this is a reference to another file that build file and that's going to be sorted work into the documentation that point in time um here's another part where where including part of the charm object model that we're trying to talk about if I
quickly goal to adopt start GeoTools . org and go to a happy little tutorial User Guide thing which storage works we should be able to find these local examples here we go it so here's a little bit of that XML file that we included and 1 thing that's really nice here is that this will stay up to date as the code base is updated so you can see that and we haven't released tools 15 yet but because this is the latest talks this fall's already been right up to date and more importantly by scroll down here somewhere there's actually source code somewhere and that is like a line code example that gets compiled as part of our documentation before the Sphinx FIL is right that help so yeah the helps a lot bigger much going you will also find that all the OSG alive documentation is done with this tool chain so it is something will see in a different post you projects thanks everyone for your time and documentation is hard to maintain so please be kind to the developers of pitch in and help out thanks MIT it
Offene Menge
Open Source
Software
Open Source
Codierung
Projektive Ebene
Computeranimation
Analysis
Formale Grammatik
Schreiben <Datenverarbeitung>
Computeranimation
Homepage
Code
Mustersprache
Speicherabzug
Translation <Mathematik>
Gasdruck
Metropolitan area network
Feuchteleitung
Softwaretest
Suite <Programmpaket>
Shape <Informatik>
Dichte <Stochastik>
Elektronischer Programmführer
Computersicherheit
Web log
Feuchteleitung
Software
Dienst <Informatik>
Menge
Suite <Programmpaket>
Einheit <Mathematik>
Ordnung <Mathematik>
SCI <Informatik>
Subtraktion
Wellenpaket
Kontrollstruktur
Beschreibungssprache
Selbst organisierendes System
Wasserdampftafel
Mathematisierung
Content <Internet>
Maßerweiterung
Dienst <Informatik>
Datensichtgerät
Homepage
Quellcode
Open Source
Mailing-Liste
Informationsmodellierung
Skalenniveau
Perspektive
Datentyp
Programmbibliothek
Äußere Algebra eines Moduls
Installation <Informatik>
Inhalt <Mathematik>
Inklusion <Mathematik>
Datenstruktur
Formale Grammatik
Soundverarbeitung
Gerichtete Menge
Materialisation <Physik>
Vererbungshierarchie
Open Source
Elektronische Publikation
Menge
Netzwerktopologie
Komplex <Algebra>
Turtle <Informatik>
Minimum
Case-Modding
Wort <Informatik>
CMM <Software Engineering>
Resultante
Bit
Konfiguration <Informatik>
Texteditor
Web log
Formale Sprache
Versionsverwaltung
Kartesische Koordinaten
Euler-Winkel
Videokonferenz
Internetworking
Maßstab
Virtual Home Environment
Prozess <Informatik>
Wärmeübergang
Bildschirmfenster
Umwandlungsenthalpie
Internetworking
Lineares Funktional
Softwareentwickler
Prozess <Informatik>
Installation <Informatik>
Kanal <Bildverarbeitung>
Applet
Web Site
Betriebssystem
Programmierumgebung
Wiki
Widerspruchsfreiheit
Konfiguration <Informatik>
Strukturierte Programmierung
Arithmetisches Mittel
Rechenschieber
Softwarewartung
Texteditor
Druckverlauf
Verkettung <Informatik>
Framework <Informatik>
COM
Verknüpfungsglied
Projektive Ebene
Garbentheorie
URL
Versionsverwaltung
Message-Passing
Google Earth
Telekommunikation
Server
Wiki
Web Site
Quader
Ortsoperator
Kreisring
Perfekte Gruppe
Gefrieren
Zahlenbereich
Keller <Informatik>
EDV-Beratung
Gebäude <Mathematik>
E-Mail
Term
Overlay-Netz
Code
RFID
Physikalisches System
Puffer <Netzplantechnik>
Benutzerbeteiligung
Task
Computerspiel
Software
Design by Contract
PERM <Computer>
Fokalpunkt
CMM <Software Engineering>
Geometrische Frustration
Euler-Diagramm
Biprodukt
Softwareentwickler
Bildgebendes Verfahren
Hilfesystem
Modallogik
Touchscreen
Elektronische Publikation
Onlinecommunity
Mathematisierung
Mailing-Liste
Vektorpotenzial
Paarvergleich
Migration <Informatik>
Ausgleichsrechnung
Fokalpunkt
Gerade
Keller <Informatik>
Design by Contract
Künstliches Leben
Videokonferenz
Mapping <Computergraphik>
Paradoxon
Formale Sprache
Touchscreen
Mereologie
Stochastische Matrix
Speicherabzug
Benutzerführung
Shape <Informatik>
Login
Vorlesung/Konferenz
Bildgebendes Verfahren
Computeranimation
Softwaretest
Linienelement
Onlinecommunity
Quellcode
p-Block
Code
Computeranimation
Programmfehler
Open Source
Software
Rechter Winkel
Stichprobenumfang
Vorlesung/Konferenz
Projektive Ebene
Metropolitan area network
Open Source
Software
Programmbibliothek
Projektive Ebene
Abstand
Code
Computeranimation
Datentyp
Vorlesung/Konferenz
Hill-Differentialgleichung
Computeranimation
Bit
Punkt
Objektmodell
Mereologie
Elektronische Publikation
Computeranimation
Caching
Stellenring
Bit
Quellcode
Extrempunkt
Elektronische Publikation
ROM <Informatik>
Code
Computeranimation
Lemma <Logik>
Verkettung <Informatik>
Einheit <Mathematik>
Code
Mereologie
Leitungscodierung
Benutzerhandbuch
Vorlesung/Konferenz
Projektive Ebene
Speicher <Informatik>
Softwareentwickler
Hilfesystem
Gammafunktion

Metadaten

Formale Metadaten

Titel Everybody wants (someone else to do) it: Writing documentation for open source software
Serientitel FOSS4G Seoul 2015
Autor Garnett, Jody
Lizenz CC-Namensnennung - keine kommerzielle Nutzung - Weitergabe unter gleichen Bedingungen 3.0 Deutschland:
Sie dürfen das Werk bzw. den Inhalt zu jedem legalen und nicht-kommerziellen Zweck nutzen, verändern und in unveränderter oder veränderter Form vervielfältigen, verbreiten und öffentlich zugänglich machen, sofern Sie den Namen des Autors/Rechteinhabers in der von ihm festgelegten Weise nennen und das Werk bzw. diesen Inhalt auch in veränderter Form nur unter den Bedingungen dieser Lizenz weitergeben.
DOI 10.5446/32151
Herausgeber FOSS4G
Erscheinungsjahr 2015
Sprache Englisch
Produzent FOSS4G KOREA
Produktionsjahr 2015
Produktionsort Seoul, South Korea

Inhaltliche Metadaten

Fachgebiet Informatik
Abstract Many people will cite how their adoption of software was based on the quality of documentation, and yet 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 accept less-than-perfect grammar.

Ähnliche Filme

Loading...