Johannes Dienst 6:18
Thanks, Brian, for having me. And also saying that you can’t get developer Doc’s right, because I’m definitely not have figured out how to do developer docs. But I want to present everything I learned in the last one and a half years of being in charge of our companies, developer docs, and taking them from very usable or usable only by TypeScript. NPM. Folks, and not any, anyone else. So one day, I’m here in the second floor, in my home office, I went down to see my daughter, and my daughter is nine years old, and she’s trying to learn crashing. And crashing is, if you can do it, you forget that there are a lot of moving parts to it. Like they have a thread on the left hand and you have to take care of it that is not too tense. And you have this strange needle hood, get overs gets tangled with the rule. And then you have to do the right patterns. And this is actually a really hard task if you’re just starting out to learn crouching. And she was like really angry, frustrated, because she watched a YouTube video tutorial on how to do a simple thing like threats, specific pattern? And I said, Yeah, it’s really hard what you’re trying to learn here, you have a lot of moving parts, and you have to be patient. And she said, yeah, that tutorial doesn’t make any sense. She got stuck somewhere, there was something missing. And also someone, the person said, this is easy. So we have basically two problems here with that approach. You have a great product, like the end product you have here, when you do cross cutting and the finished product. But the documentation was basically wrong to how to get to use it. There were steps missing. I checked it, there were two steps missing. That were I think shown but there was the hand before on the tutorial, you couldn’t make it out if you don’t know that you have to take the steps and to enrich your customer. They said yeah, it’s easy. And just like my, my daughter, she got enraged, because it wasn’t easy for her. People always get I always get angry when I tried to test a new product. And it says yeah, this is simple, or this is easy, or this is straightforward. And chatting, no, it’s not straightforward. I don’t know what to do, because I don’t know how it works behind the scenes. So and in this talk, I will try to solve these two problems or give you pointers on how to solve this problem to make your documentation better. Because I think documentation is the product to not only make or break your product, but it also is your product. And the second one is actually more easy to fix. Because you can do something like static linting for spell correction also for specific words like easy. And you can improve your documentation with this. And it also is automatic checking. So you don’t have to correct anybody, any engineer who writes documentation by yourself. But the linter does it. And if you don’t trust me, that documentation is very important. I dug up some data from slash slash data. And they said in the Developer Program benchmark in quarter three, and they asked, I think 17,000 developers from 140 countries, and that came out that documentation is the single most important resource to developers. They didn’t specify what documentation so I’m assuming it should be like video tutorials or also written documentation. But yeah, so documentation is important. for everyone. So how do we go from barely usable on the right side to usable on the left side, and one example that comes up always comes up when you’re talking about docs. It’s like the stripe documentation. The stripe documentation is perfect for this use case, you can see all these moving parts, it’s actually a little bit small, but that’s okay. You can see if and left side you have different different environments, you can play around on the right side. So for its use case, it’s perfect for developers and really cool interactive and you get to build your stuff on the stripe talks your use case, and can use it afterwards. So that’s that’s a cool thing. But broaden the horizon a little bit, you can also check something like products, they have a best developer portal that is 2022. I think it now the 2023 developer portals best developer reports about is out there. But these are from these from 2022. They, I took some examples there. And I really liked the ivend documentation because they it’s straightforward what you can do with it. Then they also combined the API docs with the docs here. And I think it also got unwrought. What I really think is cool is the platform or ES documentation on the upper right, where you can see specific directions for something someone coming to the documentation you haven’t great search for getting started, if you already know your way around, you can go directly to API docs, and you basically know where to go to get your thing started. Nope, that’s the wrong. So when I first started out, let’s get back to our use case. This is what I found. So if you look at the documentation for version zero to seven, this was September 22, of our RCA documentation here. Basically, what you see is a starting page, and then everything got reiterated what was already on your docks, which I really disliked. on your on your homepage, which what I really disliked because if someone clicks on your docks, they are interested because they think the features you have will get you will get them there. So okay, let’s go to getting started. And then we reiterated again, so these are the first things I noticed here, they have to Yeah. So basically, you have two clicks, you can already lose two people there or more percentage will always say what this is, this is too much. I don’t want to click as much developers are impatient. Like I am also impatient can relate to this. But you can also notice there’s no search. So if I don’t know what I’m actually searching for, when I type something in this, there’s no way to actually find something. When you’re looking for specific thing. thing. There’s no clear threat. So I’m here at VI ask you is, where do I click Next? You can easily not see this year, like oh, how to install it. Also, the installation guide is for every OS the same. So you have to know your way around, you have a lot of information you don’t need. So Creevy install something with NPM some dependencies. And yeah, basically, we don’t need this, when we are doing onboarding can come to some box, you can collapse. You don’t need us. We’ll see this later. And there’s basically no guidance and it’s hard to follow. Yes, I couldn’t get it working when I started to ask. But yeah, I also had to do some weird NPM stuff to get it Rocky. So it was also not really working. It just work because I knew how to use NPM, basically. So these are not the ideal docks for developers, obviously. So what are the ideal developer docks? And when we think about developers, and I sometimes get called into onboarding course, which funnily our sales department does, and the best course are the ones with real developers. Because they’re like, I want you to do this. And I need from you this and this and this. And then I can say, Yeah, I have all this because our documentation is not comprehensive. And I just give them GitHub repositories. And they give them the right pages in the documentation. And they find their way around. And next day they call Yeah, we got it working. Yeah. Cool. So specifically, developers are searching for directions. So reiterating features on your documentation page is nonsensical to them. They already know what the features are. They want to achieve a real user goal. They have something in mind like, oh, I want to automate a Mac OS desktop application or a native iOS application. So what they actually need this because they already have a use case in mind, they need directions on how to achieve this. So the documentation in the state I showed you, yeah, no, that’s not the right thing. If they’re really committed to trying it out, then yeah, they may get around to, but a lot of people will say, yeah, that’s, that’s too much clicking, I don’t know where to go, I will jump, just jump away. So when you think about documentation, and I’m still getting used to how I present this, so your product is more like a hammer to drive in the nail. So to get to the user goal. But like every tool, if you don’t know how to use the tool, it’s basically worthless. So if you have a hammer, and you want to drive a screw, yeah, that’s not going to work. And you need instructions on how to actually use the screwdriver or your tool, that’s it has to be useful. So I set out with any prior knowledge on how to do perfect structuring. But

Johannes Dienst 16:08
I started out anyway to improve this. And the first thing I wanted to do is by have this homepage there, so this is the starting page, if we go to the starting page here, we removed basically the reiteration of our homepage. And I also wanted the starting page to be a little bit more specific. So we have a good port configuration here, because we can run it and get port our tool. That’s cool. So you don’t have to install anything. But still, there is something missing. Like, I want to automate Android. Why would I do a local installation when I’m on Windows? Doesn’t make any sense in this also no explanation on why you would do that? Yeah, so works kinda, but not perfect. But we’re getting there, it’s better than before, I would say. So we don’t have to start page, we have a little bit of restructuring of the start page, that’s cool. We have, we didn’t have a lot of tutorials. So we added some hope you can see it all, a little more tutorials than before, that’s cool. To get people started, these are not perfect yet. But you can already see we have tiles so you can get your way around here. We also improve the API Doc’s because actually, wherever hilarious like, oh, we have this click function or SDK, and there was like, Oh, that was a left click. That’s all what we have at the head of the API docs. So next thing I did was like, okay, at an explanation what it actually doesn’t do an example for every every command we have here. So we have a command for everything like, Okay, this is how it looks, if you actually call it call it. And we are possible and useful. And way ahead of time, we already included a GIF, which already also appear in the code completion, if you’re running an IDE polar code, to show what it actually does. So show don’t tell stuff. Then I can come from documentation, architecture, documentation, software architecture, I also wanted a terminology here. So we had a lot of specific terminology, like we have a bounding box, somebody who’s not familiar with computer vision, which is used under the hood, maybe doesn’t know what the bounding boxes and we’re speaking all of bounding boxes in the documentation. So that’s, that’s important to get all the terminology, right. And we also expanded the troubleshooting. Because that’s important. I think troubleshooting is always important, especially if you’re doing something like like we do on your local machine, we install something on local machine or service. And there’s a lot of things that can go wrong. Maybe you don’t need this if you have a SaaS offering. But we needed this. So I think the ducks are more useful now. But still, as I’ve explained before, we don’t have real directions here. But let’s talk about beautiful first, and I have this is very opinionated, you can disagree with me here. That’s that’s perfectly fine. But I think the most beautiful dogs are the useful dogs. It’s more like design follows function. And I have a very extreme example of this. Somebody may recognize this if they’re coming from a DevOps background or infrastructure background. This is excerpt from the nginx documentation how to configure reverse proxy. And as you can see, this is bare bones markup. This is marked down with bare bones Martin, maybe even the original HTML comes out from from markdown without any styling, and I loved this documentation. It was a single page. There was no search but you can search with your browser with Command F or Ctrl F and I only use the site to confirm figure a whole reverse proxy for a project that heads six years ago. And it was perfect because I knew, Okay, when I want to configure the error page search for error, then I see, okay, this error page lives in this context, as you can see, and there’s an example. And this is usually enough to get you started. So I think it was the most useful and beautiful documentation I ever, ever used, in my opinion, but you may differ. If you’re thinking about documentation, you always should use the approach design follows function. So you can do some cooler stuff. Have to empathy. Yeah. Like the empathy platform. This is a more polished look, I would say. They have some nice gimmicks like this, where you can see all his tricks trickster thing. And also these points here are our recurring here, so there’s a great design, which goes through every layer. And I really liked this animation, you can see Yeah, okay, empathy, empathy platform is built on four layers, and you can click on this and then it pops up. And you can select a microservice layer, for example. I think this is also animated. And you can click on this, this this. So this is really cool design, we can dig down deeper in even deeper anytime. But basically, basic design for me is beautiful, if it fulfills its needs. So with that in mind, we did another iteration. And we still have the starting page. But I thought yeah, we need to provide a little bit more directions on also make it more use case based design, like not tutorials, or guides, which acts as more like a pin for everything, you don’t know where to put it. So I said, Okay, what are our users actually doing? And we restructure the menu. So we have getting started. That’s okay. You also have how AskUI works on. Sometimes. It’s interesting for me, I don’t know what this is here. And we have installing Oscar is still but what are the users actually doing? They are selecting elements because we do GUI optimization. Yeah, it’s a little bit too much here. But you can see we have text elements selector. So okay, if you want to select elements, you know where to look. Also, how do you execute on automation, this is already cool. Because you see, we have different things you can automate. Maybe you should put this at the forefront at the starting page should be there. But we’re already structured nicely. So we have different things you can automate. Integration is what you will think like continuous integration database and stuff. And also the rest remains the same. So this is already more use case based more thought out from the user side, which I like. But I wasn’t satisfied with it yet. So is this useful? Yes, but the feedback from the users, we got quality feedback there from users who onboard it, we’re like, kinda, we still have all problems, we can’t find stuff. And also sales, people who do really, really do the onboarding. Most of the time, they said, Yeah, sometimes I can’t find things I need to find. So maybe that’s not too useful. What we should do, and this is, I’m not sure if that’s the right term, and no technical writer, but I call it segmentation because we, we defined personas in a workshop, and found out with the data we had from people who were onboarding, we talked to them, and also what our tool used to do, we had like four different personas. So you should do this. If you’re doing developer docs, if you’re just marketing or doing dogs. For developers, you only really know they’re only developers not like in our case, we have some testers who do test automation, which is different. They sometimes they don’t know how to use an IDE or a code editor, or we also have people whose RPAS they know UiPath, for example, but they’re not familiar with code, they really struggle when they open Visual Studio code. Because if you open an IDE for the first time, it’s more like, Whoa, it’s so many patterns. What do I do with all these buttons? And you have to structure the way these people at best, your documentation serves all of them. But yeah, it’s it’s hard, actually. So we did segmentation and said, Okay, we need to do something like, yeah, you want to automate Android you want to automate desktop, you want to automate all that different stuff. This is where the platform is. Example comes again. They do this actually. So if you’re just starting out, you can say okay, get started. and see what platform has is all about. But we also have a developer guide, we also have API reference. If you didn’t know, I read a figure that most 50% of the API’s, 50% of the API usage is actually non developers. So it’s cool to have an API reference, or the best practice use cases. So they do some kind of segmentation here to direct the users where they need to go. And that’s the same from a FinTech company, they do this also. So we have to explore our piece how to get started and also develop block.

Johannes Dienst 25:35
So when you’re doing segmentation, you have to have user goals in mind. And now it becomes a little bit theoretical. But it’s nice to get a theoretical basis on how to structure your Doc’s, actually, and I enjoyed digging into it. So what are user goals, user goals are rooted in the real world. Like, a lot of examples I had before. Like, I want to automate an Android, I want to automate a browser farm, I want to test a specific workflow, like this is a real world user user goal. And you have to define those based on your personas at best. And I have some examples here, you can read up there’s a book, I always forget the title. So but there’s a very famous book and except us it goes to be defined for our for our documentation was the user wants to automate an Android device, or the user wants to automate a native Windows application, or the user wants to automate a native micro asset, actually, the last one we defined but nobody ever did this yet. So it’s more like Android and Windows. But that’s okay. So and then you have this user goals. And then you go to learning objectives. And learning objectives are an very interesting thing. Because they are intellectual goals, and intellectual goals, you will see how they fall into different categories. But basically, with an intellectual goal, you can’t achieve user goal, you have to combine more than one, learning objective two, three, or four, at least, to get the user to achieve their goal. That’s the thing you have to do. And I talked about categories. And there are three categories. And I brought three examples. So we have the user should be able to connect our software with their device, that’s an applicable skill. Like how do you connect, ask you it on Android device, you could, so you can actually automate it. And then it’s the user should be able to describe the different methods used to select text. So when you do GUI automation, you can do exact matching, or regex matching or contains matching. This is more like awareness, because that’s not applicable. Can’t use it. But another example would be, oh, I have this logging this logger here. And I want to actually define the different log level. And I have to know what log levels are there. And what do they do? That’s an awareness, learning objective. And then you have the comprehension, objective, and you basically need all three of those at least to achieve a user goal. You have to know which text selection to apply to a specific scenario. That’s the comprehension learning objectives. And the cool thing about learning objectives if they give you a way to modularize, your documentation. So if you only think of learning objectives, a page becomes a learning objective. And a learning objective is with a single page is modular, you only have this information on one page. And if you need it on another page as a prerequisite, for example, you can say, yeah, you have to fulfill this page learning objective. First, you don’t say learning objective. But prerequisite is you have to know this. And that’s cool. Because like in code, you don’t have an application. And your documentation becomes composable. So if you want to automate Android, you have a set up. If you want to automate, motivate Android devices, you basically have to do the setup, and do some other stuff, too. But you always have this one setup page, which is pretty cool. It makes maintenance much easier. And also lets you think about what do I want to achieve with this. And we will see, I have an example there. We really confused our users by having two pages about Android. And they basically did the same thing. But the front and also more on the one page. And on the other end. We always every week, we had questions about how to actually set up my Android device to work with your software. And you can mitigate that by doing proper learning objectives. So to summarize this, you have user goals, and you have one to N learning objectives. The user needs to go through to actually achieve their user goal. That’s how you should think about documentation. So let’s switch to our last example here. So now with this in mind, we have user goals, we have defined the personas, we have defined the user goals, and we want to do some form of segmentation. So if a user comes to our page, they actually know where to click on. We did a very basic example, don’t matter linebreak here, it’s very weird resolution. We have the Quickstart. Again, we have Windows, Android, Mac OS, Linux, and we have the enterprise checklists, because a lot of people come from enterprise, and enterprises have some weird network configurations and also restricted machines, where we put down everything you need to know on how to get your enterprise machine up to the task of running us. Yeah. So now I know if I want to automate Android. I click on Android, or I want to automate windows, that’s the most common use case, we also have different user guides for Windows, because little bit is different all the time. So now you know where to go and to get set up. And we got the feedback. Yeah, this is now much, much better. We know where to click actually. And I said, Okay, we also have another problem. Yeah, we have this. Where is it? Is it integration? No, it’s guides. We have this problem with Android. And if you look at the I think this version, can we find tutorial, automate multiple devices? Yeah, we have ultimate multiple devices, which is a nice learning objective, how can I automate like OS and Android, for example, we have some part of Android here. And it says, Yeah, you have to do this, and this and this, and this and this. And then we have the same thing. I think on setting up Android devices, it’s the same thing. More or less, it’s a little bit more, but basically the same thing. And we have also a web search and analyze, which also talks about this. And you’ll see, there was no clear learning objective behind these pages, and somebody might click the correct page to get the setup corrected. But most of the time they click the wrong page. And they were utterly confused because something was missing, or different or not correct. So in the, in the last iteration of our documentation, we have automating mobile devices. And we have Android and iOS, iOS doesn’t work, right. And this is only the set up, this is only setup. And so we said, Okay, we have the set up, and then we want to do something with it. So you get set up here. And then you’re done. And now when you’re set up, you can do something like automated web search on Android devices tutorial. That’s it. That’s pretty cool. And you also have to set up unresolved reference each other. And you only have this information in one place, you can say you have to do this before you actually start the web search on Android, which I find pretty useful. And it makes maintenance much, much easier. But it was hard to actually untangle this. So you have to watch out for this. So now, now that we know how to build the documentation, structurally, with user goals that map to learning objectives, or a path of learning or chapters, or check this, how beautiful how design follows function, actually, how do we do the docs? How do we do that? Technically? How do we generate a static site you saw here? Yeah, we do a static site with docs as code. That’s because we are very engineering heavy. Thankfully, I think we already we have like 15 engineers and only 20 employees. So that’s, that’s, that’s great. We have a lot of engineering power, and docs as code is perfect. Because you only have to write Markdown and everybody can edit markdown in the code editor or IDE, whatever they use. So the editing is easy. That’s a don’t have to say any more that the review is easy, because we can put this on GitHub, we can do pull requests, we can do some linting and all that other jazz. Or you can export codes, like markdown to every format you like, You’re not an enterprise environment, thankfully, but you can also do some styles here, like in my former former company, where you need to do some CI on every doc document. So this is possible. You have automatic versioning in your GitHub repositories, so you can bring back documentation you need your accidentally deleted and for me that’s very important. It’s not WYSIWYG it’s WYSIWYM I think they should correct this year, make it across out because WYSIWYG something like a Word or Google Docs and you only have to think about formatting and with WYSYWYM them it’s more like what you see to use what you mean, and this is a heading and let the former to take care of it and render the nice HTML.

Johannes Dienst 35:06
So the tech stack we use, a lot of people use this, I actually saw the Weaviate docs, they also use Docusuarus. It’s nice to consolidate some convenience functions. It’s built on React, you can do like the automatic versioning, we can say, okay, create a new version that does the does the version create for you, you can build it, you can extend it easily with React and JavaScript. So that’s cool. And in a former version of this text deck, we used LX, which is an inclusivity linter and spell checker CLI, which is spell checker. But recently, thinking about a month ago, I changed to whale which is also a spell checker, but also prose linter, where you can say, I want specific phrases to not appear in our documentation, as you already have noticed, with my name, and also my pronunciation and grammatical errors. I’m not a native speaker, you can ensure that your language in the Docs is easy, is understandable, accessible, and doesn’t include any profanity with Wale that’s all built into a URL. So that’s, that’s pretty cool. Which brings me to our actual docs, which live in a GitHub repository, which is pretty cool. And let’s open the structure here a bit. So when you have docs as code, and you have a linter, configured in package json, so we installed some way here, I think should be here. Or isn’t it? No, it’s not here. But you have to install it on Mac you have to install with homebrew or from sauce, you can do a lot of interesting things. So the first thing we did was to actually outsource our styles, because I want to define the styles globally. So we put them in our own repository. And then we linked them in our dot GitHub repository. So here are the styles. And some things don’t make sense to put there you also have technology that will says no, I don’t accept this. But like, for example, AskUI or Okta or Chara that bailed us know that this is not a spelling error, but introduce the economic, its own company name, so you can put the C in there except in the Alex rules. So what we do here, this is a clause this is you see, this is a symlink to a repository. And when we do linting in the pipeline, we just check out the repository with the depth one and then we can lint with the same styles globally. For every repository we have in our company. We can force the same style guide which is cool just cool and we also have a pre commit hook with Husky where you can say okay, it’s me make this a bit smaller here. You can see okay, I only want to lint when I say git commit all only want to live the air the current version like docs, Docs, AP that’s where the current version lives and all that terminology and the same for the pipeline. So if you look at the workflows we have a specific portfolio that’s just for linting which basically does the same with a specific action and says okay, we want to learn to read me and all the latest versions here. So that’s how we do do linting here this is very flexible that’s why life laughs laughs docs as code here. And what what does well do it does spell checking and I hopefully there are some arrows here in Docs. I put them there so hopefully we’ll find it. Say well, docs that’s what I do and then you get this nice nice such as a new okay, I didn’t delete it some characters here. Did you really mean Explorer? And also something like bigger that is profanity? I had to ask llama three by this is actually profanity and then they explain it to me. Because profanity in German that’s easy for me. But profanity in a not native, not native language like English is for me hard. And that’s nice to have a profanity linter here. So let’s, let’s go to what’s next. And it says in line six, much more to explore. And also an only gets bigger. That’s I put that there because yeah, that’s not what we actually want. And when I run docks, Vale docs again, then it actually says, okay, there are no arrows. At the moment. We don’t fail the build if there are arrows because I’m the only one working on the docks. usually get a PR and can fix this stuff myself. But once we roll it out, it will be easy to get the same style everywhere. And this is really nice.

Johannes Dienst 40:15
So to conclude my talk and give you some takeaways so we wanted to tackle that the structure of your documentation is like easily followed with clear steps and clear direction. You don’t you want to fulfill the developers user goals. Developers come they have a user goal. They don’t are not very interested in features. But directions. That’s what I put a short how to get there with user goals and learning objectives. Then design follows function. Okay, yeah, iterate on this long enough. So when you go about structuring your documentation, you should think about user goals first, and also the personas you expect the user goals, best thing you to do is to do brainstorming what your tool is for and also get real user data on who installs the software, then they find the learning objectives. Yeah, following the user goals in comprehensive scale, applicable skill and awareness, and also, there’s a personal opinion, use docs as code, because docs as code gives you all these cool tools like linting and stuff. And you can eliminate the easy words or the simple words that may exclude some users or enrage users. And it’s funny that Brian said, yeah, he’s not on the on the bedside anymore. I’m also not a bedside anymore, but on mastodon. So if you want to connect with me, it’s LinkedIn or Mastodon, and I’m open to questions now.

Brian Rinaldi 41:52
Sorry, hit the wrong button there. I meant to remove that. Thank you, Johannes. That was That was great. I think you really kind of clearly explained a process. What I liked about that was that, you know, obviously, some of the everybody’s doing like different scale of docks, right? Like you can, in the things you showed, could apply to like, say, a big site with massive kind of docks, or even like a smaller site with docks. So I think, you know, all those learning objectives and things like that are things you can apply, regardless of how big the Doc site you’re trying to create is. So for folks who are watching right now, if you have any questions, please post them in the chat. And I will ask you honest, before we, before he leaves, but I had some questions. First of all, one of the things I struggled with, and maybe I want to get your take on, like is, is like how, you know, one of the one of the struggles is like, there’s always a bunch of edge cases and things like that, that, like need to be somewhere in the docs, right. But I always feel like they are distracting to like the kind of normal path like, Okay, we’ve got a path that takes 70 80% of our users through, but there are an important 20% That like that. We happen to have these edge cases, and how do we accommodate them without adding in all kinds of clutter into the main path? How did you did you come across this kind of issue in your documentation? And how did you?

Johannes Dienst 43:31
Yeah, it’s unsolved problem more or less, like, as I said, we would do stuff on your local machine. And specifically on managed machines, there’s so much things that are restricted, and you have to accommodate for everything. So what I do if it’s more lengthy to for the 20% it was these collapsible admonitions, yeah, it’s detailed box. Like if you encounter this then read, but mostly you don’t encounter it. Let’s setting the execution policy on PowerShell usually, that’s restricted you can’t run anything on PowerShell on a managed device that’s how in the process work you have to contact your IT department and then that that’s where do these call outs but yeah, that that’s that’s brutal, and I don’t have a really good solution for it. Actually, yeah, yeah, I think it has boxes are really cool. And also we had this problem on Mac like we discussed before before the show, like the spaces that this virtual desktops are just weird on Mac, like the jump around that’s why we created a different path for Mac OS actually. So like, you saw in the in the last example where we said Yeah, okay. You have one for Windows, you have one for Linux and you have one for Mac. So if specific problems for Mac you have Windows user doesn’t care about. So just duplicating the thing. The page

Brian Rinaldi 45:00
Okay, and then did you What made you end up choosing like specifically Docusaurus because I know there’s lots of like, Astro has starlight. So like,

Johannes Dienst 45:12
You’re a bigAstro fan, I know.

Brian Rinaldi 45:16
So you know, that’s why I’m asking.

Johannes Dienst 45:21
I didn’t choose it. If I had chosen it, I would have use something like ASCII doc. ASCII, like Doc toolchain, from a codec for me, has it? But basically, I’m, I’m not someone who discusses technology. I think I saw it. I used it and thought, yeah, that’s good enough for now. And that’s it. And the cool thing, what, because it’s extensible, so you can customize it very easily. And if you know, react, then you can do something like the feedback button by yourself. So it’s cool. And also as a plug in system, so it’s not a bad system. And I evaluated it and said, Yeah, that works for

Brian Rinaldi 46:01
me. Ya know, I’ve used both resources and start like, and they’re both really good, different I, you know, my only favoritism for, like, Doc, you source. Sorry for Starlight is just the having to have yakked for the entire docs, you know, like, is it necessary? So, we do have some questions from the audience, though. I want to get to them. So first, Claudia asks, do you consider effective the way that the ASP dotnet core documentation gets started part is done. Instead of segmenting by platform, from the beginning, they created a path and inside each part of the path, you created tabs to show the how the command can be done in Mac, Windows, Linux, whichever they show the command. So basically, instead of like doing how you did splitting into the operating system, they would show that you have a single path, but with multiple tabs inside there showing how to do things. And

Johannes Dienst 46:59
yeah, I think selenium does this also, like you have this different languages, what they did, they also duplicated, a check the source code, the duplicated the pages, just change the source code, which I think is a little bit maintenance heavy. And this part, I think it depends on what you’re actually trying to achieve. So we had this before where I said, okay, the installation path is different for Windows, I think we also have this in our documentation right now. So when it fits, I only want to have one page and something like this taps, like different types, you have to run this command on Windows, you have to run this command on Linux and this command on Mac OS, because it’s different if you run this in a PowerShell than on a Mac OS terminal, for example. So I want to have it like this, like Claudia said, Yeah, I agree with that. But basically, we also have different installation routines for Mac OS, and Linux and also windows at the moment. And we want to get to one installer. But we’re not there yet. So I had to just split it up. Because so different. You couldn’t combine it in one page. But yes, I wanted. Actually, I wanted to have it in one page, because for patients to choose from, introduces error.

Brian Rinaldi 48:14
Yeah. You know, we, one of the things we struggle with, I know like, I’m not on the ducks team, but I know the ducks team, like, we have so many different languages. And that’s one of I mean, we can’t, there’s places where you can have overlap, you know, other places where you can, or even can’t like, we have 30 SDKs, right, like, how do you watched any? Yeah, how do you put like, Oh, here’s the example in Ruby in JavaScript and Python in Java. And like, you really can’t do that. So I think, you know, one of the other challenges they I know, they face is like, weird. What is the right? choice there in terms of like getting most users to a point that they can understand the concepts but like without overdoing having to maintain 25 Different examples, right?

Johannes Dienst 49:06
Yeah, but I saw the Weaviate docs, they’ll have like five examples. I really liked the review docs. On also the long chain docks, I think they have this different. Yeah, there’s different tabs. So this is more like a common approach. And I also liked the taps more because you don’t have to duplicate everything. I don’t know why the Selenium. I think they also used to consoles, but they didn’t use the tabs, but they use the duplicated the pages. And every time you change the text on one page, you have to change it on every page. So huge pull requests. I think it’s a maintenance horror nightmare.

Brian Rinaldi 49:47
Okay, so Margaret asks, as a lone person working on the docks, how do you measure the effectiveness of your docks once published?

Johannes Dienst 49:55
That’s a good question. We have this feedback button, which barely Someone clicks. The main thing I used to Gosh, effectiveness is talking to our sales people always talk to developers and also get feedback from from my salespeople, or every everybody who uses the docs internally. Because I have the luxury that Ron my colleague shoutouts to him, he has to do with ducks in a product and talk to customers a lot. He gives me feedback and says, Yeah, I don’t get it. And he’s the ideal customer, because he’s technical, but not a developer. So for us that that’s perfect. Yeah. But it’s hard to Gosh. And I always use every single new person who comes into the company has to go through the onboarding. And I’ve watched them and I, then I see, okay, that’s the problem.

Johannes Dienst 50:48
Yeah, I think I mean, the feedback buttons can be helpful. I think also, you know, a lot of times, yeah, if you have customer support, some sort like getting waiting, hoping, hopefully, some of these external inputs can kind of like community, you know, Slack or things like that, where you can find, give people an opportunity to like, share issues they ran into, I think, but I haven’t heard of anybody has like a perfect way of gauging. Especially with developers, you come as a developer check it and doesn’t work, and then you just churn. Now in my position, I know how important feedback is I usually give feedback to open it. But

Brian Rinaldi 51:36
yeah. Okay, so a couple more questions we’ve got here from Simon. Simon asks, How do you obtain and handle feedback from developers using the docs? I think you kind of answered that. Like, it’s basically that feedback.

Johannes Dienst 51:49
Yeah. We also repository and you can open issues. I think we had one issue yet. We are mostly b2b, we want to be b2c. But usually we get the feedback directly from customers when they say, I couldn’t get to set this up. And every time someone comes and says, I couldn’t set this up, I look at the docs. And then then I realized, because I was looking so long at it, and I think yeah, okay, that’s not clear. I have to improve this.

Brian Rinaldi 52:18
Yeah. Okay. And Simon’s other question was, have you observed developers doing particular test to see how they work with the docs? And where they get stuck? Like, do you do any user, like, user testing kind of thing?

Johannes Dienst 52:33
Not yet. But that’s also because our customer bases, just small, but we do a thorough onboarding and assess people or sometimes I’m, I’m there and observing them. And then we usually get to the pain points where they say, I need this resource, because the risk is developers can usually point out where they get stuck, and what they need. But we don’t have qualitative feedback or survey, like the circles,

Brian Rinaldi 52:57
a technical issue. Yeah, okay. Yeah, I agree with that. I mean, it’s really, it can be very, you know, those, those kinds of tests are difficult because you, it’s easier when you have a small, like, the scope of your Docs is small, but as it gets much, much bigger, right, like, I think, you know, those are useful, but you also have, like, how many of those, you’re not going to have tons and tons of these? What did you call them that like kind of your use cases, but like, you know, you’re gonna have so many of them, like, okay, I can test certain things, but I’m not going to cover if you’re coming for this one particular use case, I will, you know, can’t necessarily test I can

Johannes Dienst 53:38
only do a developer experience audit for this specific use case and see if the docs work.

Brian Rinaldi 53:43
Yeah. So you know, I’ve, I’ve worked on some smaller docs, and it was easier because it was like, Okay, we’re new, we don’t have that much to cover. And then as you get to, like, you know, row and Company, the, you know, the product expands, it’s like,

Johannes Dienst 53:58
yeah, the stripe books are big. Manga. Exactly.

Brian Rinaldi 54:03
I know. And yet, there’s still always like, the canonical example of like, these are great developer gods. Yeah.

Johannes Dienst 54:09
Yes. You know, a few when I researched this talk. So I know. I know. Like Vivian in long chain link chain was was also perfect. And the nginx on my favorite, yeah. Okay. Basically, I opened the site where weather alarm integration wasn’t only open decided to get it working. I was like, Cool.

Brian Rinaldi 54:29
That’s, that’s cool. That’s good to know, actually have that link chain on my like, I want to check it out. Like I haven’t messed with yet. So that’s good to know that the docs are good. All right. Johanna, this was a really great presentation and really enjoyed the talk. I really appreciate you coming out and talk to us. I know it’s late where you are so very much.

Transcribed by https://otter.ai