Still waiting for someone else to do it: Writing documentation for an open source project
This is a modal window.
Das Video konnte nicht geladen werden, da entweder ein Server- oder Netzwerkfehler auftrat oder das Format nicht unterstützt wird.
Formale Metadaten
| Titel |
| |
| Serientitel | ||
| Teil | 124 | |
| Anzahl der Teile | 193 | |
| Autor | ||
| Lizenz | CC-Namensnennung 3.0 Deutschland: Sie dürfen das Werk bzw. den Inhalt zu jedem legalen 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. | |
| Identifikatoren | 10.5446/20334 (DOI) | |
| Herausgeber | ||
| Erscheinungsjahr | ||
| Sprache | ||
| Produktionsort | Bonn |
Inhaltliche Metadaten
| Fachgebiet | ||
| Genre | ||
| Abstract |
| |
| Schlagwörter |
FOSS4G Bonn 2016124 / 193
8
20
21
27
28
34
39
51
53
56
61
64
66
68
72
75
78
79
80
84
104
108
112
120
123
126
130
131
134
135
140
142
143
145
146
153
154
157
160
165
182
183
188
190
00:00
UnrundheitWort <Informatik>Vorlesung/Konferenz
00:34
Konvexe HülleRechenwerkSupremum <Mathematik>Metropolitan area networkPerpetuum mobileLokales MinimumOpen SourceProjektive EbeneZahlenbereichVorlesung/KonferenzComputeranimation
00:59
Bus <Informatik>Computeranimation
01:20
Bus <Informatik>Workstation <Musikinstrument>Treiber <Programm>Schreiben <Datenverarbeitung>BenutzerschnittstellenverwaltungssystemMultiplikationsoperatorVerkehrsinformationQuaderFigurierte ZahlEinfügungsdämpfungComputeranimation
01:56
EinfügungsdämpfungOpen SourceEinfügungsdämpfungProjektive EbeneComputeranimation
02:13
SoftwareVideokonferenzMultiplikationsoperatorLeistung <Physik>Projektive EbeneZahlenbereichSoftwareVideokonferenzMAPSystemaufrufOpen SourceVersionsverwaltungStandardabweichungKonfiguration <Informatik>HypermediaFrequenzComputeranimation
04:21
Keller <Informatik>SpezialrechnerSharewareLokales MinimumInnerer PunktSummierbarkeitMetropolitan area networkDesign by ContractSoftwareentwicklerMAPMaßerweiterungSoftwaretestWikiCodeÄußere Algebra eines ModulsProjektive EbeneProzess <Informatik>SoftwareentwicklerSoftwaretestCodeMultiplikationsoperatorKomponententestMaßerweiterungWikiTypentheorieSoftwarewartungMathematikObjekt <Kategorie>OrtsoperatorWeb SiteMereologieOrdnung <Mathematik>Open SourceBildgebendes VerfahrenInklusion <Mathematik>Komplex <Algebra>ZahlenbereichProgrammierumgebungInhalt <Mathematik>InformationCASE <Informatik>VersionsverwaltungTouchscreenEreignishorizontCodierungRechter WinkelZeitdilatationPunktTaupunktComputersicherheitServerZentrische StreckungKonstanteEndliche ModelltheorieResultanteComputeranimation
10:12
Open SourceProgrammierumgebungElektronische PublikationWeb-SeiteServerSoftwareentwicklerDatentypHilfesystemProdukt <Mathematik>Inhalt <Mathematik>Dichte <Stochastik>AuszeichnungsspracheFramework <Informatik>QuellcodeTouchscreenDatensichtgerätEindringerkennungCodeKlasse <Mathematik>Formale SpracheAppletSpezialrechnerDatenverarbeitungssystemBildschirmsymbolTexteditorGeometrische FrustrationWort <Informatik>Web logVererbungshierarchieZeitrichtungGoogolPunktRichtungBrowserOffene MengeW3C-StandardNavigierenTermSchnittmengeFormale SpracheWeb logSoftwareMultiplikationsoperatorFeuchteleitungInverser LimesWort <Informatik>Physikalisches SystemWellenpaketObjekt <Kategorie>ÄhnlichkeitsgeometrieVersionsverwaltungMinimumSpezifisches VolumenHilfesystemTypentheorieTouchscreenTextsystemWikiCodeProjektive EbeneBrowserAlgorithmische ProgrammierspracheRichtungSchreiben <Datenverarbeitung>DatenstrukturGruppenoperationFunktion <Mathematik>Reverse EngineeringOpen SourceZählenBitVerschlingungTabelleInhalt <Mathematik>QuellcodeDateiformatDichte <Stochastik>DifferenteDokumentenserverGüte der AnpassungElektronische PublikationTexteditorKontrollstrukturSoftwareentwicklerFormale GrammatikGeradeMereologieKlasse <Mathematik>MathematikVerzeichnisdienstHierarchische StrukturPunktFigurierte ZahlUmwandlungsenthalpiePerfekte GruppeZahlenbereichComputeranimation
16:04
EinfügungsdämpfungTreiber <Programm>GeradeArithmetisches MittelMetropolitan area networkPunktWort <Informatik>Bus <Informatik>InformationComputeranimation
16:35
BinärdatenZahlenbereichFormale SpracheExistenzsatzMultiplikationsoperatorE-MailQuellcodePunktMailing-ListeMereologieTranslation <Mathematik>ZeichenketteQuick-SortElektronischer ProgrammführerWort <Informatik>VektorpotenzialÄußere Algebra eines ModulsEigentliche AbbildungRohdatenRepository <Informatik>SoftwaretestOpen SourceMaschinelle ÜbersetzungPhysikalisches SystemProjektive EbeneEinsFlächeninhaltVerschlingungMathematikPerspektiveObjekt <Kategorie>ForcingSoundverarbeitungServerProgrammierumgebungWald <Graphentheorie>Uniformer RaumVerteilte ProgrammierungMultiplikationArithmetische FolgeWhiteboardKonditionszahlComputersicherheitIntegralOrtsoperatorComputeranimationVorlesung/Konferenz
22:02
Open SourceProjektive EbeneLesen <Datenverarbeitung>Vorlesung/KonferenzComputeranimation
Transkript: Englisch(automatisch erzeugt)
00:09
Okay, thank you everyone for being here. I'm Julien Saint-Lacroix, working at my gears. I'll be, I'll chair this session. And please welcome our first presenter, Mike Pumphrey, working for Bondless,
00:20
who will talk to us about the challenge of writing good documentation and getting the community involved. Get a round of applause, please. Thank you. So, my name is Mike Pumphrey, and I've been involved in documentation on the GeoServer project for a number of years,
00:41
along with some others, and I'm here to talk about writing documentation for an open source project. So we'll start here. Oh, yes.
01:07
Pesto. It's a ruin outside of Salerno in Italy. And many years ago, my friend and I were backpacking around Europe, and we went to see these ruins, and we took a bus there from town,
01:22
and my friend left his wallet on the bus. And so it was very distraught. The next day we went to the police station and to write a report, and I actually, while he was at the police station, I went back to the bus, the same bus station that we took the bus from at the exact same time, and I needed to tell him, the bus driver,
01:40
my friend lost his wallet, blah, blah, blah. How do I do this? I know zero Italian. So I look up my phrase book, and I have no time to figure this out. The bus arrives, and I come up with this. If you know Italian, please don't laugh. Because it means, to lose wallet yesterday,
02:01
it was the best I could do. Now you might be asking, what does this have to do with documentation for an open source project? We'll return to that question later, but bear with me. So let's talk about the challenge here. You work on an open source project.
02:20
Think about it. If someone spends $30,000 on software, they're gonna have a lot of investment into learning how it works. They might spend a very long time trying to get it working and understand it 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 success or give up?
02:44
Will they quit or move on if they don't get a quick win? That is the challenge. So documentation priorities. If you're just looking at the high level, there are two big priorities. Number one, you need to tell them how to install the software. You cannot assume that this is something that is going to be easy.
03:02
Number two, you need to get a quick win. You need to get a win so people say like, ah, I've got the software and I see a thing. So I work on the GeoServer project. So what's our quick win? Seeing their data on a map in GeoServer. Win. Everything else is subservient to that. If you don't get to those two steps, it doesn't matter anything else you write about
03:22
because they won't be reading. They will have moved on to something else. So installation is used as a sanity check to tell if things are going okay. You do one step at a time. Don't waste time explaining other options. Remember, at all times, your software is being evaluated.
03:42
This is not the power user stage. This is the, if it doesn't work, I'm gonna go buy something else or download something else. Videos are great, but they tend to be a little difficult. It gives you a sense of hope. Someone did it. Someone got it installed. I mean, I can't be the only person that's had trouble just getting the software working. This is why I spend so much time on this.
04:03
Version videos are difficult because they go out of date. And so generally speaking, don't recommend videos so much for the installation. Save that for the cool features that the software exhibits once people have gotten them installed. So the quick win, call it the quick start. It's a little misnamed because,
04:22
well, it shouldn't be misnamed. It should be quick. It's not always quick. But the objective is to go from just installed to something on the screen that's awesome. So that's the second step. You do one, then you do the other. What are other places that people get caught up in? There's Stack Exchange.
04:40
Well, we don't need documentation. We have Stack Exchange. Stack Exchange, for those who don't know, is a Q&A site. It's very popular with GeoServer, GeoTools users. It's kind of like an alternative to a user list, but it's not documentation. It, however, can be used as documentation supplement in the sense of questions that asked repeatedly
05:03
may point at a whole like, oh, people are always asking about this. Maybe we should write about it. So when you're working on open source documentation, when you look at a project, one thing that I have found that is always an issue is curation. Curation is difficult. Let me give you an example of that.
05:22
I don't know how many people are familiar with GeoServer. 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 at a GeoServer code sprint in January, and I found this gem.
05:40
This is great. It was an image that was in our documentation. This is from GeoServer 1.7, which was released before 2009, and it was in our documentation as of 2016. So the first thing you can learn is that when I'm speaking up here, I am not the example that we always have to model.
06:01
We are doing our best, but there's always room for improvement. So curation is difficult. Curation is also slow. Last year, Jody Garnett, my colleague, gave a version of this talk at last year's Phosphorgy, and he mentioned how there was a new feature in GeoServer, which was the GeoFence security system.
06:20
GeoFence has a UI, and it said, look at our documentation. We don't have any. It was sad. I'm happy to report that this year, we actually do have something, so curation is slow, but it does happen. But it doesn't always happen. For example, last year, Jody also talked about the fact that this complex feature example, this is in GeoTools, didn't have a code example, and unfortunately, I just checked last night,
06:42
and no one submitted anything just yet. So this is a problem. So maintenance and QA can be the first thing to go. Like for example, features get dropped, and the documentation can stay. We have some stuff in there that was, oh, that feature was taken out, but no one was involved.
07:04
So sometimes what happens is that code gets produced, and it's done, and we got paid. Hooray! But then if there wasn't any facility for documentation, then oh, we'll get to it later. And we know when later is, later is never.
07:24
So GeoServer originally had a wiki for its documentation. Anyone can edit it. The problem is is that GeoServer's not Wikipedia. We don't have this critical mass of people who are saying like I am knowledgeable about a certain thing. They're not either knowledgeable enough or motivated enough to make wide-scale changes.
07:41
Your community cannot do all of the work for you. If you work on a project, there's certain things that you need to be able to be proactive about. So we actually ended up ditching the wiki because it wasn't actually working for us, and we tried to create a more structured environment. So I'll tell you about that as well. The important thing is that on any project,
08:01
you can have the community do work for you, but you need a gatekeeper or a curator, someone to say, okay, that's the work you've done. Now I'm going to put it in position. I'm going to approve it just like you would with code. So this is something that we adopted at Boundless. A feature is not done, it's not completed until it's documented. I would say we're pretty good about this.
08:21
It's kind of a motto, even our developers know it now. They say like, oh yeah, it's done, but I have to do documentation. It's kind of like unit tests. It's something that you need to do as part of the process. It's not done otherwise. So we're not always 100% successful on this, but everyone knows it, and we build in time. We build in time in the contracts and in the work we do.
08:44
So I'm not a developer. A lot of the things that I write about, I only, I didn't understand it a few days before I wrote it. So what I found that works is two things. Number one, if I can get a developer that's worked on a project or worked on a feature to just write some limited information,
09:02
just really raw stuff, and then I can translate that because I have the experience about writing and putting things in order, and I've been doing this for a number of years. Other thing that I found that works is that I interview a developer. You get your curator to interview the developer and say like, hey, what does this do? Why do I care?
09:21
And that usually allows me enough information to be able to write something from there. So for example, another way to get documentation to happen is that you include it as part of your software policy. So GeoServer has extensions, official extensions, and in order to be approved for inclusion in the project,
09:42
it requires documentation and tests. If you want in, you have to document it, and as a result, the documentation for the extensions now include a much better job of documenting the new features. So like I said, GeoServer, originally before, I've been involved for a couple of years now, but originally it was actually just raw HTML.
10:02
I didn't know about that, but someone told me that, and it was moved to the wiki, and like I said, the wiki didn't work, and then what we decided to do is that documentation has the same types of issues that code does. There are versions, there are versions, and there are features that are associated with them, and we want to know who did what,
10:21
and so we basically decided that we wanted documentation to not live outside in some wiki in some other system or WordPress or what have you, is that documentation is really just code. So we decided to put the documentation in the code. So treating docs as code allowed us to do a lot of neat things.
10:42
So if you're curious, we have for many years now used a documentation generator, it's called Sphinx. It was originally designed for Python output, but it can basically do anything, it's very versatile. The nice thing is that it builds documentation from a structured text format,
11:00
and it can build it in many different formats, HTML, PDF, and LaTeX, and some other formats. So you write it once and you can generate it in a lot of different formats. The structured text is actually known as restructured text. It's similar to Markdown. You can see a title and a subtitle, and there's a link in there.
11:21
It's kind of like a rich text, but it isn't Markdown, it's just similar to it. Nice thing about Sphinx is that because the documentation is treated as code, they are right next to each other in the directory hierarchy of the repository. So Sphinx allows us to actually include code in the documentation.
11:42
You see there's a literal include at the bottom. So that is actually pulling in the source code. So if the source code changes, the documentation never goes out of date. One less thing to have to keep up. So when we took away the Wiki, alas, people still wanted to contribute.
12:00
Some people do, and they're very motivated, and we want those people. We want to support those people. We don't want to give them too many barriers to helping the project. So now that we have the documentation in code, we can utilize the same types of procedures that other GitHub software projects have. So anyone can edit in just four simple steps.
12:21
You go to the documentation, it's right in the GitHub repository. And GitHub allows you to edit files directly. So anyone can do this. You need to have a GitHub account, but you don't need to have commit access. So we have limited the barrier to entry so that all you need is a GitHub account. Edit the file. You know, if you find a typo, I want to fix that typo.
12:41
You know, I always want to fix typos. That's my, that's how I got into this gig. Step three, you just use the built-in editor. You don't need to install Sphinx. You don't need to install Python. You don't need to install anything. You can just say like, I found a little bit of a typo. I wanted to add this thing in. And then you modify the file.
13:02
Step four, you click submit. And then if you don't have commit 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 evaluate it and we either make the change or send it back saying, hey, this breaks something. But either way, the person has done the work and they've contributed.
13:24
So some writing tips for quick. Never say it's easy. You want to know why? Because it's not easy. If it were easy, then you wouldn't need to be here because they would have figured it out and they wouldn't be reading your documentation. Similar, never say simple or simply
13:42
because you're going to make your users feel stupid if they can't figure it out. Just simply a matter of, no, it's not 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.
14:02
We don't want to hear your opinions here. Write a blog post. Similarly, no marketing. Great and cool, easy way to do awesome things. They know it's awesome. They're going to figure it out. If your software is awesome, they will know. Be professional. Don't use slang. Some people are coming from a language that's different from the language that you're writing in.
14:23
When you're learning a different language, the last thing you learn is humor because it's the nuances of the language that you don't get. So if you say, fire up your web browser and point it in the direction of, some people who don't have that command of English would be like, fire up, what? It doesn't help. Finally, assume longevity.
14:42
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 edited. So assume that you're writing for the future. Assume that you can be as generic as possible.
15:01
I like to, when I do screenshots, cut out anything that makes it obvious that it's a specific version number because that way, when the next version comes out, all of your screenshots haven't gone out of date. So you do a little bit of work now so that you can do less work later. Finally, if you take nothing away from this,
15:21
remember that the phrase is not, don't let perfect be the enemy of the good. The phrase is, don't let good be the enemy of nothing. Your goal, if you're a 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.
15:41
You just need something. Something is better than nothing. Now as a grammar nerd, I have a lot of trouble with this because people submit things and I just, I want it all to be correct and bad grammar makes me twitch and it's just, misspellings stick out to me like nails and so that's been a challenge.
16:02
But I always keep in mind that the point of words is to communicate information. And as the philosopher Chuang Tzu said, words exist because of meaning. Once you've gotten the meaning, you can forget the words. So where can I find a man who has forgotten words
16:21
so I can have a word with him? So let's return to that bus stop. I went and I said this broken Italian phrase to the bus driver and believe it or not, he actually had my friend's wallet. Somewhere in there, I think there's a lesson.
16:42
Thanks. Thank you very much. And so now we'll have time like seven minutes for questions, so any questions in the room? Feel free, everyone.
17:01
Thank you. So when you brought up Stack Exchange, I was thinking it would probably be a good idea to go back the other way. So once you've found, this is something we should document because people keep asking about it, you might want to go back to those questions and create an answer that points to the new documentation
17:23
once it exists so that people can find it. It's a good idea. Or yeah, I guess it's better than hoping that Google searches pick it up. But yeah, no, that's a good point. People will be finding it on Stack Exchange once the question exists. So you probably want to link to it that way as well to think about going back.
17:42
To round trip it. So if people are not going there, they're coming back. No, that's a very good point. I read recently that Mapbox have installed an automatic testing system for their documentation. So it finds marketing and useless words
18:00
and points them out. I'm sorry, it finds what? Marketing words, some useless words. Really? Like and so on. And well, automatically tries to, well, inform documentation writers about it. I like that. I like that a lot. We have, at GeoServer, we have a style guide
18:21
so people can read the good things to do and the bad things to do, but it's definitely not automated. I kind of love that idea though. Other questions? How do you handle screenshots? Do you have any automated way to reprocess screenshots
18:41
on this in a while, or do you render them manually every time? What do you mean? In the documentation, the screenshots of the different areas, do you redo the screenshots manually every time, or do you have an automated way to create them? Well, we don't have an automated way to create them,
19:02
at least with the tools that we use, but what I always recommend is 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 for it to go out of date. Thank you. And there was a question.
19:22
Yes. So I'm just interested in translation as well. Do you have any experience or any tips like how to set up a proper translation systems? I've already heard of Transifex and GitHub. So not as part of the documentation per se,
19:41
but in GeoServer for the actual strings in the UI, and sort of that area, we do use Transifex, and we have a number of languages that that's set up for. We don't really have a facility for automatic translation of the raw documentation itself. That's kind of, I mean, I think there's a lot of work
20:01
in that environment, in that area, but I think auto translation of words is not, yeah, it's a challenge. So we have relied in the past on people who wanted to make translations to actually make the translations themselves.
20:21
More questions? So maybe a last question. What do you think would be the best way to start contributing to the GeoServer documentation? So for anyone who is interested in contributing to the GeoServer documentation, easiest thing to do is, I would recommend joining the mailing list
20:42
and getting involved that way. We have a GeoServer users mailing list. You can download, you can look at the source code there and read the documentation. We have documentation online, 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,
21:01
I think usually you figure it out pretty quickly what you're likely to want to do. So definitely get involved. Just a second. You showed you you're using Sphinx, right? Are there any alternative in the open source world for documentation? Because I've seen most of the projects
21:22
use just this tool, Python-based tool, but are there any alternatives that you evaluated? I'm familiar, sometimes I've heard MakeDocs, MKDocs is another one that I've seen people use as another documentation generator. There's a few of them out there. That's the only one I've heard recently,
21:40
though a lot of times they're not even really using so much of the documentation generator. A lot of times they are using Markdown and keeping it in the GitHub repo and keeping it very simple. But yeah. Thank you. Any other questions? No? Thank you, Mike. Thank you very much.
22:00
And hopefully you will have a generated interest in concentrating in any open source project documentation.