Developers Documentation: your secret weapon
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Number of Parts | 112 | |
| Author | ||
| License | CC Attribution - NonCommercial - ShareAlike 4.0 International: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/60791 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
EuroPython 202226 / 112
5
10
14
17
19
23
25
29
31
32
34
44
47
51
53
54
57
61
69
70
82
83
88
93
94
97
101
105
106
00:00
Software developerAreaGoogol2 (number)Goodness of fitSystem callMultiplication signComputer animationLecture/ConferenceDiagram
00:54
Shared memorySoftware developerTwitterData miningMultiplication signTheory of relativityGoodness of fitSource codeComputer animationDiagram
01:32
Software developerRelational databaseLink (knot theory)Multiplication signTwitterSoftware developerProcess (computing)FeedbackDiagramComputer animation
02:38
Software developerProcess (computing)Workstation <Musikinstrument>Goodness of fitProduct (business)Presentation of a groupQuicksortLecture/Conference
03:25
Software developerINTEGRALProduct (business)Presentation of a groupProduct (business)Service (economics)Online helpSoftware developerMereologyBitNeuroinformatikPoint (geometry)SoftwareLecture/ConferenceComputer animation
04:46
Point (geometry)Product (business)EmailNumberInternet forumTwitterBuffer overflowStack (abstract data type)
05:34
TwitterProduct (business)Different (Kate Ryan album)NumberTheory of relativityComputer-assisted translationSoftware developerSystem callSound effectPoint (geometry)Process (computing)BitMereologyVirtualizationInternet forum40 (number)Meeting/Interview
06:58
Software developerVideoconferencingBlogProduct (business)Sound effectPoint (geometry)Content (media)Process (computing)MereologyInternetworkingYouTube
07:50
Process (computing)TelecommunicationFunctional (mathematics)Object (grammar)Social classProduct (business)Source codeType theoryData managementInformationContent (media)Computer configurationSoftware developerLink (knot theory)Multiplication signService (economics)Condition numberNeuroinformatikUniform resource locatorOrder (biology)Online helpWorkstation <Musikinstrument>BitPRINCE2Computer animation
11:16
Pointer (computer programming)Optical character recognitionoutputAsynchronous Transfer ModeMaxima and minimaLevel (video gaming)ParsingSoftware developerData managementAutomationMeta elementMachine visionSoftware development kitProduct (business)Projective planeCartesian coordinate systemPoint (geometry)Multiplication signService (economics)WordInformationMereologyResultantKey (cryptography)Set (mathematics)Web pageRight angleSelf-organizationCategory of beingComputing platformComputer clusterCAN busError messageLecture/ConferenceXML
14:00
AuthenticationOptical character recognitionoutputAdditionSoftware developerVariety (linguistics)AutomationTotal S.A.TowerVideo gameMultiplication signCountingProcess (computing)Key (cryptography)InformationSystem callReal numberBitHypermediaCategory of beingForcing (mathematics)Right angleCodeJava appletSoftware development kitXML
16:00
SoftwareKey (cryptography)Software developerPasswordLoginWindowProduct (business)CASE <Informatik>Condition numberInstallation artMereologyTouchscreenCartesian coordinate systemLecture/Conference
17:44
MereologyTouchscreenComputer animation
18:17
Product (business)Video gameCellular automatonService (economics)Focus (optics)Content (media)MereologyInformationTouchscreenComputing platformMedical imagingConnected spaceKey (cryptography)Link (knot theory)WeightComputer animationLecture/Conference
20:17
Key (cryptography)Key (cryptography)BitComputing platformFreezingLink (knot theory)Web pageFocus (optics)Letterpress printingRectangleDrag (physics)
21:31
Focus (optics)TouchscreenRectangleKey (cryptography)MathematicsVideo gameSheaf (mathematics)Web pageBitComputer animation
22:08
Key (cryptography)Open sourceWeb pageKey (cryptography)Sheaf (mathematics)Computer configurationFocus (optics)Operating systemSinc functionMenu (computing)InformationMultiplication signTunisVideoconferencingMedical imagingGroup actionGoogolCartesian coordinate systemTouchscreenComputer animation
24:00
Web pageProduct (business)CodeMultiplication signState of matterParameter (computer programming)HTTP cookieRight angleCone penetration testLecture/Conference
24:51
Integrated development environmentGoodness of fitCodeProgramming languageInheritance (object-oriented programming)Product (business)Formal language
25:38
Product (business)DebuggerMaxima and minimaError messageBlogCodeGoodness of fitLibrary (computing)Lecture/ConferenceComputer animation
26:26
Product (business)Computing platformLibrary (computing)Line (geometry)CodeComputer configurationMultiplication signPlug-in (computing)NumberLecture/Conference
27:15
InformationWhiteboardLink (knot theory)XML
27:48
Process (computing)Condition numberProduct (business)Goodness of fitMereologyContent (media)Different (Kate Ryan album)Medical imagingVideo gameComputer animation
28:37
Different (Kate Ryan album)Medical imagingMathematical optimizationCASE <Informatik>Connected spaceDependent and independent variablesLecture/Conference
29:18
Dependent and independent variablesSoftware developerDifferent (Kate Ryan album)Computing platformType theoryLaptopNeuroinformatikPasswordMetropolitan area networkLecture/Conference
30:09
Computing platformMenu (computing)MereologyAdditionMathematicsMaxima and minimaCodeProcess (computing)Group actionCondition numberType theoryComputer configurationFormal languageAugmented realityMultiplication signOnline helpInformationOpen sourceWebsiteObservational studyAxiom of choiceRevision controlWater vaporProduct (business)Fluid staticsSoftware developerRight angleHand fanOpen setComputer animationMeeting/Interview
33:04
Link (knot theory)Medical imagingGroup actionSoftware developerMultiplication signCondition numberLecture/Conference
33:48
Multiplication signView (database)GodComputer animation
34:30
Multiplication signWebsitePoint (geometry)Product (business)SoftwarePower (physics)Goodness of fitService (economics)BitComputer animation
35:04
Online helpContent (media)BlogPoint (geometry)WritingSoftware developerMereologyProcess (computing)Lecture/Conference
35:45
Finitary relationSoftware developerDirectory serviceMereologyControl flowProcess (computing)FreewareZoom lensMultiplication signTournament (medieval)Interior (topology)TwitterDrawing
36:36
ForestProcess (computing)Shooting methodLecture/Conference
37:18
Web pageCodeBlogOpen setInformationBitKey (cryptography)Process (computing)Condition numberExecution unitOpen sourceCoefficient of determinationGoodness of fitAugmented realityLecture/Conference
38:43
MereologyGoodness of fitLevel (video gaming)Latent heatRight angleProduct (business)Point (geometry)Disk read-and-write headCASE <Informatik>Queue (abstract data type)Lecture/ConferenceMeeting/Interview
39:58
WebsiteCodeDensity of statesPresentation of a groupPerfect groupLecture/Conference
40:34
Product (business)Software developerPerfect groupProcess (computing)Term (mathematics)Right angleMultiplicationLatent heatLattice (order)MereologyDifferent (Kate Ryan album)Video gameComputing platformCondition numberData miningCombinational logicLecture/Conference
43:02
System callSpeech synthesisTwitterEvent horizonLecture/ConferenceXML
Transcript: English(auto-generated)
00:07
Pretty good? How was the conference so far? Yeah, good, good. That is my second time in Dublin. And let me tell you, like, someone doesn't want me to be here. You know, the first time I was joking with local people, it was during winter.
00:22
And I was like, oh, you call this a winter? I'm from Canada. This is not winter. And I caught a call right after saying that, like, the day after I started to cough. And I'm like, are you kidding me? Like, I just, like, made a joke about the fact that it's not even cold for me. And this time, my luggage decided to stay in Canada.
00:40
So I'm wearing the same clothes for the last four days. It's not true. I went to do shopping. I changed my clothes. But still, still. Anyway, it's always a pleasure to be here. My name is Fred Frederick Harper. Why that thing is showing. I'm sorry. Let me hide that. Sorry about that.
01:15
I'm a director of developer relations at Mindy. And during the talk, if you want to tweet about stuff, take pictures of my ugly face,
01:23
share good things, bad things, feedback, questions that you don't want to ask in person, or if you don't have the time to take a lot of questions, things that you disagree with, feel free to do it on Twitter. I spend way too much time there. My Twitter end goal is Hefharper, F-H-A-R-P-E-R.
01:41
And I struggle saying my whole name. So today I'm going to talk about developer documentation. And the fact that it's your secret weapon. I'm trying something new also this time. If for whatever reasons you don't want to give me feedback in person, you don't have time or you don't want to ask questions, either you're too shy or you feel like you should not ask this in public,
02:04
or it's really, really mean feedback and you don't want to say it in my face, there's that link that I'm trying recently. It's ngl.link slash Frederick Harper. They didn't have Hefharper available. And you can send me anonymous question. And like anonymous question, like there's no way for me to know
02:23
where it was sent or who sent it unless I pay like 60 bucks per month, which completely defeat the idea of like having something anonymous. So yeah, you can use that more than happy. Yeah. So on that note, okay, I need to print the clicker. We only have 45 minutes.
02:41
And I don't think I know people in the room, but if you saw me in other conferences, if you follow me online, you know I talked a lot. Actually, this is my job. I'm being paid to talk. So 45 minutes for me is like not enough to talk about developer documentation. So what I'm going to try to do today is to give you as much of,
03:04
like many tips about developer documentation, the importance of it, how you can make a good developer documentation, and how can it help your business or your company or your product to be, or yourself to be more successful. So the idea is like a bunch of tips and also guiding or guidelines
03:23
to really give a better experience to your users. So let's start with a quote, because every good presentation has a quote. Your developer's documentation is an integral part of your product. One cannot exist without the other. I need to point that out. And that person who said that is me.
03:43
Yes, I'm quoting myself. But joke aside, one cannot exist without the other. I'm a little bit exaggerating here. Like it's not totally true, but still, it's really part of like, if you have, you can have the best product out there. You can have a wonderful product that solves all my problems or that helps me to be more productive as a developer.
04:03
But if I go on your documentation, any documentation sucks. It's not good. It's not interesting. It doesn't help me to do what I have to do, or it's really difficult to understand, or it's not up to date. There's a chance I don't like your product. There's a chance I don't know how to use your product. There's a chance that I will never use your product
04:21
and just go see and use a competitor or use another product or another software, another services out there. So documentation for developers for your product is critical, is really, really important. So there is more than like being successful overall. There is many opportunities that come with great documentation.
04:47
Oh yeah, that works. So the biggest thing is that documentation is kind of like the foundation, as I said, of your product. It is the one point of entry to your product that people will use.
05:01
So you want to extinguish fire even before this start, and your documentation will help you to do that. So first thing first, you know, when something is not working, people will complain on Twitter. People will try to contact customer support. If you have great documentation, you will minimize the number of people
05:21
that will need to send you an email or contact customer support or go on a forum or ask questions on Stack Overflow about your product. If your documentation is well written, you're going to minimize the number of people that need support. You're going to minimize the number of customers that will complain about your product, because we're all really quick, especially developers,
05:42
we're really vocal when we don't like something on Twitter, on different forums, on Slack, on Discord. We are really good at that. I don't know for you, I'm really, really good about that. I complain a lot of Twitter. Actually, I would say my Twitter is about 50% cats
06:01
and 49.9% should post. So that's basically what I do on Twitter. And you know, when something is not working, people complain. When people complain, it means that they're not happy. And everybody is an influencer. Not in like, oh, I'm an Instagram influencer,
06:20
influencers on the beach and taking pictures, kind of things. But you know, you always influence something. You all have a personal brand. So if I say product X is not good, maybe some of my followers will see that, maybe some of my friends, maybe some of my co-workers will remember that the data want to use that product, the product X, and will say, you know what?
06:42
I'm not even going to try it. Fred, try it. He didn't like it. Not because I'm good or I'm better than other people. It's just because we have a relation and if I'm complaining about something, that may become the truth for those people. So great documentation would minimize that. It's also going to create a kind of like love effect.
07:03
So people will like better your product because they're going to know how to use it. That's going to be faster for them to use it. And on the contrary of people that are complaining, they will become what I call virtual evangelists. You know, part of my job as a developer advocate is to help developer being successful. And I do that by speaking at conferences, creating contents online.
07:22
But the benefit with having a community around your product, with having people that love your product, is that at some point those people may start to think, to talk about your product in a positive way. Either, like I said, just with people around them, within their network, or they're going to write blog posts, they're going to create a video on YouTubes, and it's always heartwarming
07:41
when people from the community does that. It's always exciting when someone is vocal, not for the negative stuff, but for the positive stuff. That may save you money because, again, the time you spend to explain things to people, the time customers support, answer the same exact question again,
08:02
it's not worth it. Actually, it's worth it because it's for your customers. But there is a way for you to save money on that. And a good thing that I do, an example with the sales team, is that if they ask often the same question, I ask the sales team or the marketing team at my company, like, please let me know, and we're going to update the documentation,
08:20
or we're going to have a section, so next time you won't have to explain this again, you can just send a link. So I see documentation as one link to rule them all. Like, that should be the resource that you send to people when they need help, when they don't understand something, or when they want to use your product. Obviously, also, you know, not everybody knows what you know,
08:42
and even not myself, I know what I know sometimes. So you will be surprised how often I go check my own documentation to know how to do something with my product because I just forget because there is many things many tech stuff, so that can be helpful for you too. And by writing documentation yourself as a developer,
09:02
I know, I know, most developers don't like to write documentation. You just need to check source code to understand that we don't like to write documentation. We don't like to write how things work. But as a developer, I think we're in the best place to create that documentation, a great developer documentation for people, and by doing that,
09:21
that's going to help improve your communication skills, which is a soft skills that is not in most job posting, but it's always something that hiring manager want. Even if you work in front of a computer, even if you're like I'm a developer, like typical little more introvert, a little more shy type of developer, you still need to communicate with people, either with customers or with colleagues,
09:43
or with other stakeholder in the business. And because we work, especially right now, in a remote world, you do a lot of text-based communication. So writing documentation, it seems far-fetched, but that's going to help you to be a better writer, which is going to help you to be a better communicator.
10:02
So it all starts with the content. It's documentation. Big surprise. It starts with the content. So first thing first. If you have a developer documentation and you don't have a search option for your documentation, I want you to get out of that room
10:21
and go have that search feature right now. Stop listening to the talk. Go have the search feature. There is nothing more annoying than you go in the documentation of a product, a service, and you don't exactly know what's the name of the feature or the name of the classes or the object
10:41
or whatever you need to or the function you need to call, but you have an idea about what you want to do, and there is no way for you to search that information. So that is the first step. Even if your content is not good, if you at least have a search bar, that's going to be useful for people. That's going to be a great feature that you absolutely need to have.
11:01
One of the premises that I start when I need to write new documentation or update documentation or take ownership of documentation is that for documentation, the details, the details, every little details count. Every little things that you can make a little bit better, every little typo that you can fix, every little things that you can just improve in your documentation
11:24
is worth the time when it comes to the documentation. Because, again, think about this as the foundation of your project or your product or your service. Think about this as the first point of entry to your application. The second part, which is also important,
11:42
is how you organize the information. Because you can have all the information, again, you can even have the search bar. If it's difficult for me to see a nice path to, okay, starting from the first part, which is probably creating an account, to the next step is probably, I don't know,
12:00
creating an API key because I'm going to call it an API. The next step is to try a kind of like hello world example. If it's scattered around in my documentation, it's not really clear that there is a true path from beginning to, okay, now I have a result. It may not be the result I want, but I have something that is working. It's not going to be interesting for people.
12:20
So let me show you an example, what we've done in Miami. So, again, you can go check the documentation. I think it's pretty good. I don't think it's perfect. I think there is always a place to improve what we're doing. But I'm pretty happy where we are right now. And if we check to the left, which is like the important part right now,
12:41
is we have a lot of pages about a lot of things. Not that our product is complicated, but we can do a lot of things with it. But if you, I don't know if this is going to work. It doesn't matter. If you look at the top, get started. This is, if you never use Mindy, this is where I want you to start. It's quite obvious, get started.
13:01
So where is it? Right at the top. So you have welcome to Mindy. What is Mindy? Set up your account. Make your first request. And after that, I'm going to do a platform tour because the first thing I want to do, I don't know for you, I'm not the most patient people in here. So when I want to try a service, an application,
13:20
whatever I want to try, I want to try it, and I want it to work right now. Again, even if it's the simplest usage ever. We have an API. I want to try the API. I want to have an answer, actually, a positive answer, not an error, from the API. Even if it's basic stuff. So I know it's working, and I know, I know, I know that I know how to use it.
13:44
So that is the first step. But because it's in kind of like category of topics, if you already use Mindy, you don't care about getting started. You can go to account and organization setting or you can go to the next step.
14:03
The other thing I want you to do, once you get started, I'm sweating like a pig. It's super humid here. Actually, it's even cold this morning. What the hell? You know Dublin this July? Is it July or August? I don't know. Is it July? Yeah, okay. I'm a little bit lost. 2020.
14:21
It's 2020? Yeah. Yeah. Yeah, it's the third years of 2020. Second year. Sorry about that. It's like 4 a.m. for me. So the second thing you want to do, I want you to do, actually, because I tried to guide you in the process.
14:41
So once you get it started, you create your account, you get your API key, you make your first call, something real basic, but you make your first API call. Okay, now after you may want to set up your account, have more information, billing, if you want to pay, because we have a free offer, but if you want to move to the next one, we don't force you with this. But the other thing is that it's an API,
15:01
so you can use it whatever you want, but what I really want you to do, and I'm not going to force you, but what I really want you to do is to use your SDKs, and we're still building some, so we're going to release the Java SDK and the Ruby SDK once I'm back from the conference, but right now we have fight on the node,
15:20
and because it's the first thing I want you to do after, like I don't want you to code everything, I want to make your life easier, and at the same time I want to make my life easier, because if you use the SDK, it's going to be way easier for me to help you if you have any issue, or to debug things or support you than if I have to support your own code. So I'm going to put that right after,
15:40
and after that, you know, it's category and category and a lot of things. So that was the closest pictures of Jon Snow, which is not Jon Snow. That gave me the commercial copyright that I could use. So one of the other saying or premises that I write documentation, when I write documentation or I update
16:01
or I review documentation, I need to think about Jon Snow. You know nothing. So write your documentation like if the person was going to read your documentation, know nothing about your product, know nothing about the technology you're using. You don't have to write everything,
16:21
but at least maybe you can point them to external resources, like if you need for the SDK, Python SDK, I need to do a pip install, and maybe the person is not proficient in Python or never use Python. I'm not going to rewrite how to use those tools, but I may point to an external resources on the Python documentation about how to do that.
16:42
But when it comes to my own software application, I'm going to write every little detail. Oh, you need to click next to go, next button to go to the next window once you enter your username and login and password to connect. And you need to enter the API key in that field.
17:02
Why is that? Because again, not every developer has the same skills or expertise as you or has the previous person using your documentation. So by doing that, you're helping people that are new, again, to your technology or the technology you use, but it's still going to be easy for someone who have a little more experience
17:21
or know your product to be able to just skip through the more interesting stuff for them. So always start with the premise that people just don't know what you're talking about. So more details is better than not enough. If you have pictures, screenshot, images,
17:41
please, please, please put great quality one. Take great quality screenshot. So the first thing is the text. The text is the most important part of your documentation. But I don't know the percentage, but most people are visual. We are visual creature. Put great screenshot, put great images,
18:02
put high definition, great quality. There is nothing more depressing than like a well-written documentation outside of not having the search bar to have like just crappy screenshot, even if I don't use them or I don't need them. It's just ugly. And that gives the impression that you do not care about your documentation
18:20
or you do not care about the quality of what you put on your documentation. And people are really quick to make one plus one equal two or three, depending on where you come from. It's like, yeah, okay, if you don't care about the documentation, maybe that person doesn't really care about their product. So it seems obvious or it may seem stupid what I'm saying right now,
18:41
because I say a lot of stupid things in my life. But it's really important, because again, it's about the quality, it's about how people perceive your documentation slash your product slash your service slash your company slash even yourself. Try to also, if you take screenshot, try to focus on the information that the people need.
19:02
And when you take screenshot, another important thing that is really helping the accessibility or make your documentation accessible is that everything should be text-based. The screenshot should be just another way to have the information that you've already written. So don't use the screenshot as something that is needed,
19:24
absolutely needed for someone to use your product or to understand how to use your product. So people with screen reader will be able to still use people that are visual impaired or people that have issues like getting the content of your documentation,
19:41
people that are in really, really slow connection can still have access to the text-based information. And the images are just a plus, another way to consume the information. So try to put everything, actually not try, do it, put everything text-based and use the screenshot of picture just as an addition, not as a main part of the content
20:01
in the sense that if I remove the pictures, I don't know how to use your product, I don't know how to use that feature to understand that feature. That is super important. But also, as I said, focus on the information. So you know here, I have a part in Mindy platform where I can create an API key to access my API.
20:23
So real basic stuff, you click on the button, but still, it's a whole page. If you don't know the platform, you're like, okay, there is a lot of button, there is a lot of links there. So if I show that screenshot, I'm like, okay, I'm not really pointing to what I want the user to do.
20:41
So what I'm gonna do first, yeah, actually, it's not even that, that ugly black bar, it's just ugly, it's just taking the focus, like my eyes goes directly on the black bar that is hiding my API key and it is not where I want the user to focus. So use great tools to take screenshots. There is a lot of tools out there,
21:01
some freeze depending on the platform and you can do something a little bit nicer like this. Actually, it's really simple, but is it nice? Like nobody's like, yay, that is so nice. Yeah, oh, thank you, thank you. Tough audience. But I feel that is nicer, but that's just the first step.
21:23
The second step is like, okay, I need you to create an API key. So yeah, I'm gonna put like a big red rectangle around it. Again, quite ugly if you want my taste. So I can have something where I'm gonna dim everything around the button. Now, okay, I still have the focus. Now I go right there. There is not that ugly red rectangle around it.
21:43
I can still see the rest of the screen. But if you tell me your eyes didn't go right through creating a new API key when I change the slide, either you're a liar or you're a liar. Your eyes went there. This is where I want you to have the focus and it's just a little bit nicer. So again, going back to the devils in the divo,
22:02
the devils is in the details when it comes to documentation. Now I want you to go to the next step. Like next step would be even to, okay, I don't need a full page. Maybe I just want to show the section where I need to create the API key that I really need in my documentation section
22:21
about creating the API key to show all the page with all the options that will take the focus away, that will people like me who have a really strong ADHD will focus on everything else except creating the API key, or will focus on creating the API key and oh, a screw up, a screw up, or like a new option menu. So I'm going to click there. I'm going to forget what I'm going to do.
22:41
So by taking a screenshot that is more focused, that's going to help the user. So a tool that I use, I'm not getting paid to do that. I just really love it. Actually, I paid to use that application, the paid one. If you're using Mac, CleanShot is really, really good. But it's just one suggestion. I just really love it. It does everything that I've shown you. You can take scrolling image, video, whatever.
23:02
But there's a lot of tools out there. Unfortunately, I'm not going to propose any more tools like in that talk because I didn't try other tools since forever. So I don't want to say, oh, use that tool is good. But anyway, you just check like ScreenShot tool. You can even use like the basic tool that comes with your operating system.
23:20
But at the end of the day, if you just go to take a better tool, there is a lot of open source one. There is some that you have to pay really, really cheaper and expensive. And to give you the small option that really changed from like a boring, ugly screenshot to something nicer with just the small options that I've shown you, you know, really able to focus, hiding information in a better way,
23:42
focusing in a better way in the information. And you just go on Google, Bing, whatever you use, Alta Vista. It's been forever. And you search like, you know, ScreenShot tool for your OS. You're going to find some. One of the things that people doesn't do because once you wrote the documentation, you're like, okay, I'm done. I'm tired.
24:01
Like, I already didn't want to write the documentation. Yeah, no, take the time to review your documentation. And when I say review your documentation, there's two things you can do. First, read everything and do it step by step, like if you were a new user. So you have a page about creating a new account? Don't do it because you know it.
24:22
Read the documentation, create a new account, exactly how the documentation is written. By doing that, you're going to see if you made a mistake, if you had assumption because, you know, you know your product. The second thing is try to get another person, someone that didn't write the documentation, to review the documentation for you.
24:41
That's going to be really helpful. The other thing is that don't just review the text. Review the code. And you would be surprised how often, maybe it's just me, but how often I look at the code and the documentation, wait, that looks good. But like if I copy and paste, so I don't write it down, I don't look at it and write the same code, no, no.
25:01
I copy and paste, select, or if I have a copy button, I select the code, I paste it in my IDE or whatever I'm using to run the code, and I try it. Because if I write it down, I may make mistakes, I may fix mistakes. Now you really copy and paste the code and try it.
25:21
It's super important because, again, it's the basic on your documentation. And you know what, what I do, I told you before, what I do is like when I try a new product, even if I know the technology, even if I know the programming language used, I'm still going to copy and paste the code example, the documentation, because first I'm lazy,
25:41
and secondly, I want to try it as fast as possible to see, again, if I can just have like the minimum like return or whatever result that I'm looking for with the product. So copy the code and try it, and you're going to be surprised to see how many little mistakes we do. It's like when we write code, you know,
26:01
everything seems fine, you try to run your application, and like, oh, mistakes, or the debugger gives you like an error or something like that. So it's the same thing with documentation. I was like, why did I put that image? I have no idea. Yeah, I just remembered now. The second thing that is super important based on what I just said
26:22
is have a small copy button. It seems stupid, and it's really not complicated. There is like a JavaScript library out there that does it for you, or plugins, or depending what platform you use for your documentation, there is a lot of options to make it really easy.
26:41
Have that small copy button, because, again, lazy, I want to go fast, and most of the time trying to select the code from documentation does not always go well. Sometimes you're going to get like the line number, you're going to get the text before, you know how it is.
27:01
It's not always going super well, and, again, I want this to be fast, I want this to be easy, especially at the beginning when I'm evaluating your product. So have a copy button. I don't know why I'm speaking kind of like an English accent. If you want to have more information about documentation, you want to bounce ideas, this is the community
27:23
you want to go or be in, Write the Docs. It's a conference, but it's also a Slack community. It's, again, one link to rule them all, writethedocs.org. There is a lot of resources on the website. Community, it's a lot of technical writers by profession,
27:41
but also a lot of people that have to deal with documentation, and it's just like it's the place to be or to go for more information about documentation. Great example of documentation, Stripe, a really good one. They do a great job with the API, they do a good job with overall documentation.
28:00
Twilio is a really good one. GitHub is a great example with API documentation and just like visual how to use the product documentation, and there is another one which is like really, really good. Oh, come on. This is the last one, really, really good. The second part is important, it's the container.
28:21
So, you know, you have your content, but if the thing you use to display the content or to give the content to people is not good, you're not going to have a great experience, so it needs to be fast. And again, you're like, hey Fred, good job, Captain Hovius. Yeah, you're going to say that to me, but like how often you go on documentation is just slow, it takes forever to load, so make it fast.
28:43
Optimize the image. You can optimize the images without losing quality, like think about people that have slower connection because we're pretty lucky many places in Europe, many places in North America and different places in the world we have fast internet connection, but it's not always the case.
29:01
And even in places when we have fast internet connection, I don't know for you how many people are not from Dublin, but like if you travel just once or twice and you need hotel Wi-Fi, you know what I'm talking about. So try to make those things fast. Try to, and I can't believe I need to say that in 2022, make your documentation responsive.
29:23
And the funny thing is that I didn't know, but there's a developer that just like used their phone to check documentation. For me, I need a computer with like two monitors and like unless like without that I'm dying, but people use their phone, people even use their phone to code, which I was like surprised, and it's nice, it's good, it's just not for me.
29:42
But I need to think about the users or I need to think about someone who just need to check something quick on their phone, they don't have the laptop or there's an issue with the laptop, whatever. No matter the reasons, your documentation should be able to be consumed in any type of platform with different viewport. Make it easy to manage,
30:02
make it easy to use. So as a user, like I don't want to have create a username password to access your documentation. I want to have like a nice menu with a nice organization, so make that platform easy to use. And make that platform also easy to maintain because I know we're developers, we want to create things,
30:23
but when we think about stuff like documentation, the goal of having documentation is to write the documentation, to give the documentation to people. The goal is not to maintain the container of the documentation. So just reuse some things out there. There is a lot of great tools out there for the documentation.
30:42
Something that is nice too, you can use GitHub or GitLab to have your documentation, make your documentation open source, even if your product is not. Anyway, documentation is public. So put your documentation in GitHub, people will be able to submit PR, that's going to be easier for you to follow up with different versions. Basically, it's file versioning, so that's going to be helpful for you.
31:01
And that's going to maybe have people help you with the documentation, and it doesn't need to be on GitHub. Like we use ReadMe. It was not my choice, but we use ReadMe. And there is an option where people can suggest modification of the documentation. And we got people that we don't know that fixed a typo for us, or had a little more information about something that we thought were clear,
31:22
but if they had that information, it was not clear. So try to empower your community to basically help you and help themselves. So there is a lot of great opportunity out there. I usually suggest Markdown as the main language, because it's just easy to use, it's quite common. I know I'm at a Python conference right now, but still, I'm going to talk a little more about RST after.
31:44
ReadMe is a great platform if you're mostly the only one working on the documentation, only one person, or you do minimum change once you wrote the big part of the documentation. If you do too many modifications, too big of a modification, it just goes a little bit crazy. But if you're working on something that's going to be closer to kind of like a GitHub PR type of process,
32:05
by the end of the year, from what you told me, it's a great platform still. So DocuZorious, it's open source, it's really a good platform for you out there. There's also ReadTheDocs, which is quite popular. And, you know, any static site generator is good.
32:22
And thank you for the water, but I'm not sweating because of that. I'm just like, it's freaking humid. Python here, RST, Restructured Text, which are personally not a huge fan. I don't know if I should say that. I prefer Markdown. Okay, you never heard me say that.
32:40
But you can use that with Sphinx, which is quite like the most popular documentation generator out there. If you put comments in your code, you probably already know how to use RST. So those are the two that you can use to generate your documentation pretty easily, even with like, you know, in your CI CD pipeline, or if your documentation is on GitHub,
33:01
or you release the SDK and you want to generate the documentation at the same time, you can use GitHub Action. So it's good for everything, but it's really working well with RST, especially as Python developer. So in the end, you know, documentation is important. So try to create great documentation.
33:21
And you may try to find the link between that image and what I'm just saying. I really don't have no idea. Sometimes I put images, I should really put comments. But I really don't know what it was. Oh, yeah, I didn't remember. That's crazy. I was going to say, like, you may have listened to all the talk,
33:43
or keep yawning like Mr. Dare was dying during my talk, but that's a joke. It's fine if you were bored. Or just tired. Did the party last night? Nobody knows who I'm talking to. I'm talking to everybody who thinks that I'm not talking to.
34:02
So joke aside, you may finish the talk and say, like, oh, Fred, like, everything you said was super obvious. And I'm like, I agree. I agree. That's not the most, like, oh, my God, like, everything that Fred said was, like, mind blowing. But now take your time, take five minutes after my talk.
34:20
Go check your documentation and see if you follow every tip that I said. And let's talk again after to see if, like, everything I said was obvious. The other thing is, like, you know, it's right now is a good time to build and to make your documentation better. So after the conference, try to invest a little bit of time like that.
34:41
Or try to talk to the people that are responsible for your documentation to make it better. Because it's really your superpower. As I said, it's the point of entry for your documentation. It's the place where people get their first opinion after your marketing website about your product, software, or service. So it's really your superpower if you do it well.
35:00
But that can be your kryptonite if your documentation is not good. Start writing. Start writing yourself. You're just going to get better. I know you may not like it, but it's getting easier and easier. The more you write, the easier you get. And maybe at some point you're even going to start to write blog posts. You're even going to start to write more content to either help share your passion or your expertise
35:24
or just trying to help building your personal brand. So one of the other things you can do, if you don't want to do everything I just said right now, maybe hire a technical writer at your company. Or try to hire maybe a developer advocate, which part of their job will be to write the documentation.
35:43
But don't think about the documentation as an afterthought. It really should be part of your development process. So on that note, my name is Fred. I know I speak way too much. I spoke way too much, like usually. So we still have one minute for questions.
36:00
But if we don't have time, grab me in the conference break room or whatever. Send me an email, fred at mindy.com. I'm on Twitter, F Harper. If you want to chat more about documentation or any other topic, urban mental illness, you can book a coffee chat, if we don't have time, I'm on the conference at fred.dev slash coffee, 30 minutes on Zoom for free.
36:24
I'm just sharing with people. So any comment, question, insult? Thank you so much, Fred. May I? Yes, yes, of course. Actually, we have six minutes for questions.
36:43
Awesome, thank you. So I'm also a strong believer in documentation, but I also want to talk about or ask about the elephant in the room. It takes a lot of, of course, effort to maintain it, and to be honest, like if I was only doing this all day, I would probably shoot myself,
37:01
because it's not really, like, it's a fact-less job. So what would be your answer to, like, API documentation or even UI documentation gets outdated very quickly, so how to keep it up to date and not go crazy? What would be your answer to that? Yeah, it's sort of hard not to go crazy.
37:21
No, but I would say try to find the right middle. So that may not be the perfect solution, but maybe try to generate the documentation from your API. So try to document your code. So it's still writing stuff. It won't be a step-by-step, but at least you're going to have, like, basic, like, information about how to use the API. So I may not show you, like, how to create the API key on the web page things,
37:42
but at least I'm going to know how to, like, use the API. So I would say, like, that's the basic things you can do. Try to merge, like, coding, put a little bit of, like, information in your code comments and, like, generate the documentation, again, using RST and Sphinx to generate the documentation. So, again, not going to be perfect,
38:01
but it's going to be a good first step to help you and not, like, go crazy. And I understand, like, I like writing blog posts. Documentation is really not the things I like to write the most, and it's why on my job the first person I hired in my team was a technical writer. So that could be another good solution. You can hire a technical writer or use a freelance technical writer, which is going to help you to write the documentation at the beginning,
38:23
and after that you just have to maintain it. But, again, like, put it open source, so even, like, your community can help you maintain that thing. So try to outsource things that may help you. Thanks for the question. Hey, Fred. Thanks for the solid talk. It was good. You seem to have thought way more about documentation than I.
38:42
So I wonder what's your opinion on, because most of your talk is about, like, pros, documentation, high-level stuff, but there's also, like, reference docs for, like, API and whatnot. What do you think is the right balance? How do you know when you're done with one and you can focus on the other? How do you know it's good enough? Sorry, I missed the last part. How do you know it's good enough?
39:01
How do you know whether you want to focus more on the reference documentation compared to the pros, like, the high-level docs? When do you know you're done? I would say, you know, it's good enough when most people can use your product without asking you questions. I would say it's, like, at that point it's good enough.
39:22
Or don't ask you basic questions. Like, if they have, like, a specific use case, like, okay, yeah, I'm not going to document any, like, specific little use case, but, like, if I would say 80% of the people or people can do 80% of the stuff, I would say it's good enough. But it's really, like, I just put this out of my mind right now.
39:42
There is no statistic, no research about that. It's just in my head. I would say it's good enough. Because, again, the devil is in the details, but at the same time, like, if you always try to improve the documentation, there is no end. So you need to find the right and middle. I don't know if that answered the question. Yeah, okay, awesome. Thank you.
40:01
We have three more minutes, and I also have to check if we have any remote questions. Okay, perfect. Thank you for the presentation. I loved it. So I have a question. You mentioned mostly writing the documentation for the code you own, you build. Sometimes when you're working in the larger team,
40:22
that means that it's a collaborative effort. So I would like to hear any thoughts, tips, recommendations, dos and don'ts about collaboratively working on documentation. Yeah. I would say, is there anyone working at Readme? Okay, don't use Readme, because we had a lot of problems.
40:42
Like, it's a great platform, but not if you do a lot of modification and you collaborate with a lot of people. Again, they're coming. I complained to them. I had a meeting with their PM or whatever. Like, they're going to improve this stuff right now. It's not there yet. Use a tool that makes it easy. And just don't think about technical people. You know, one of the things, at the beginning,
41:01
when I arrived at Mindy, I was like, yeah, we're going to move things in Markdown, put things on GitHub. That's going to be easier for me to review. We're going to be able to track better. We're going to be less dependent on Readme. And it was perfect for me and my technical writer. But the less technical people that wanted to help with the documentation were not about to, like, use the process really easily.
41:21
And they were thinking, like, you know, reviewing PR on GitHub, where there is a lot of text and it's not code, it can be difficult. So try to use a tool that's going to make your life easier, that is easy to use, technical or not technical people, because the goal is not to be a developer when you do that. The goal is to be a writer. The second thing is, like, just define the priorities
41:43
because there's always a lot of things to do. So what is the most important? What will have the biggest impact or the biggest negative impact if we have it or if we don't have it in the documentation? And try to have people review stuff, because especially if you write documentation about your own stuff, the things you build, it's clear in your mind.
42:02
You may think it's clear when you write it down, but try to have someone who didn't work on a product or that specific part of the product to review it. That would be the quick, like, three, four tips that I would have for you. Yeah. Try also maybe the last thing also. Try to, without having, like, forget how you name that,
42:22
but, like, a convention about, like, the tone and voice of the developer documentation, just try to have some basics about, like, how you should write. You know, like, hey, we're going to write in the terms of, like, mindy, has mindy, not has, like, Fred who's writing the documentation. Or we're going to be, like, professional and make no jokes.
42:42
Like, just try to have, like, five or six, like, basic, like, how documentation should be written. So if there is multiple people, different people writing the documentation, it doesn't seem like there is multiple people writing the documentation. It seems like it's one person writing the documentation because it's always written about the same way.
43:02
Perfect. Thank you. Thank you very much. Fred? Thanks, everyone. Have a great rest of the conference. And, by the way, tonight, for those of you that don't have ticket for the social event because it's full, I'm going to go to, like, a brewery ten minutes from here. So just ping me on Twitter if you want to join
43:20
so I'm not drinking alone like an alcoholic. So, yeah. Thanks, everyone.