Johannes Dienst: Useful and Beautiful Developer Docs and How to Create Them

This talk focuses on the importance of creating useful and visually appealing developer documentation. The speaker, Johannes Dean, discusses his experiences and lessons learned while managing documentation at his company. He emphasizes the significance of avoiding the misleading notion that certain tasks are 'easy', especially for beginners, and highlights how flawed documentation can hinder user engagement with software products. Dean presents strategies for improving documentation through a clear understanding of user goals, modularizing content, and effectively utilizing tools like Git for version control and linting to maintain quality. He also shares insights from developer surveys showing that quality documentation is essential for user success. Recommendations include refining documentation structures, offering real-world examples, and engaging with users for feedback.

[Music] ladies and Gentlemen please welcome our next speaker Johannes Dean presenting the topic useful and beautiful developer docks and how to create them hello hello that so funny when the AI pronounces a German name it's actually yanes but nobody can say that outside of Germany of course cool you're all here always some enthusiastic people in the front which is cool after lunch so hopefully nobody's falling asleep

because the topic is one close to my heart and uh it's a condensed talk of everything I learned uh about developer dogs in the last one and a half hours it being in charge of the develop dos of the company I'm employed at so one day I come down from my home office it's two floors up in the under the attic and my little daughter she's nine

she learns crotching and has somebody done crotching yeah somebody actually if you can do it it's pretty easy you know the steps to start and that stuff but when you think about it it's a very finicky task you have this thread and it has to wrap around your finger and has to the right tensent then you have this stupid needle who gets hung up in the wool

and you all have to use this funny patterns no don't want to enable dictation you have to learn all these patterns to make a beautiful like hat or something like that and she was sitting there nearly into tears and very enraged because she couldn't do it yet and I said to her yeah what you're doing is actually very hard when you start out you have to learn

all the things that go into it it's it's a a process and then she said yeah but I watched this tutorial I did everything the the lady said I should do but it didn't work out H and then I watched the tutorial myself and so oh yeah there were two steps hidden behind the hand in the tutorial my daughter because she didn't know what was missing couldn't

complete it so the tutorial was faulty and she couldn't learn how to crotch it this specific pattern right and there was another thing that enraged her because the tutorial said in the tutorial the lady said yeah that's easy yeah maybe for me because I can crutch it a little bit but if you're just starting out no that's not easy so and these are the two things I

learned about documentation and this is just a tutorial um never ever tell someone something is easy when they're just starting out or even when they experience never ever do this and if you have faulty documentation or no documentation at all basically no one can use a product that's how it is and in this talk we will tackle both both problems here like documentation how it makes or

breaks your product and how to improve your documentation so it supports your product and uh how to get rid of those easy and simple steps that actually are not easy by Static linking and using doc and if you don't take it from my uh little anecdote here you can trust the experts SL data they conducted a survey with developers over 140 languages um not languages countries for

over 14,000 developers answered this uh developer program benchmarking survey and one of the key findings was documentation is the single most important resource to developers so if sucks your product sucks that's how I this so now let's start how do we get from the right side like oh I want to use this product but I don't know how to the left side where say yeah this is

a great product I can use it I can support case of course if you think about great docks who heard about the stripe docks already a few everybody who thinks I need to improve my Docs Google how to improve my docs and there's the stripe documentation because it's mentioned all the talks like I did this is a a wellth thought out document documentation it's way overboard it's

custom build also there's no framework on it like doosa or another static site generator framework so yeah you can aim for this but actually it's over the top they're way ahead of all all the other documentations but there's also developer portals and um there's also award yearly award I think this is from 2022 there's also the 2023 award already out and there are more cool examples of

documentation like the Ivan documentation they also made a very cool blog post that's on the left side how they fuse the API dogs and the SD case with all things in this documentation so this is cool also the plate dogs which are nice and clean I think and I love the documentation platform for platform OS because you have this nice search bar and also some segmentation so

you get get guided very very uh effectively so when I started out one and a half years ago let's see how this works this a small uh was task the first task was okay get our product in installed yeah and uh I went to the docs naturally that's what I do and what a lot of developers do if they want to try out your product and was

created by this like what is this a repeat of our homepage totally unnecessary so okay I clicked and I was already annoyed then I get here and uh again I get reiterated why we should use aski okay I already read your uh read your homepage so why should I read this again I want to get installed and these are only the obvious thing things you notice like

you already lose developers because they have to click two times you have to minimize the click things what I also noticed was oh there's no search bar so if I search a specific thing it's not here then I have to click another two times to actually get started and installing RSI and uh you can run us on every platform Mac OS Linux and windows uh problem is

every installation proc procedure is different for each platform so a little bit and there are also specific ways it could go wrong and you have one installation and you have way too much detail to get started like okay install all these dependencies and he this is what they actually do like who reads this if they just want to try out your product yeah so I was not

happy with it and funnily enough it didn't work at the start so we had a our customer profile is more like someone from testing who does know a little bit of test automation they often come from Java or python yeah I could get it to work because I came from typescript at a time I know how to my way around to npm but we had a lot

of problems with customers who just came from python was were thinking like what does this strange npm error mean also the API dos which is more like for experienced yeah click yeah it clicks an element no examples no use case on where you want to actually do it what is Click Mouse left click tab Mouse right click no explanation whatsoever so yeah this helps a lot if

you're using SDK in just learning no not really so these very obvious and then I thought okay uh let's get a little bit more methodical and uh thought about okay what do I want from a developer perspective so how do we make our docs useful and if you're thinking about developers and I hope a lot of developers are here and uh sometimes they get into sales calls

and our sales people try to explain the SDK or no code platform to their customers and the best customers are actually developers because they say I want to do this and I need resources from you and then I point them to five resources and an example repository and they just go off and the next day they write an email yeah we got it to work perfect developers

are cool yeah um the funn thing about developers is that they usually come with a real goal in mind they're not coming to your tool and say yeah I want to install a vector store and use it that's not how you as a develop approach product it's more like I build an retrieval augmented generation example just to learn some stuff and that's how I come to select

a vector store it's not like oh I want to try a vector store no I need a vector store to actually do something in the real world so throw all those features out of your documentation you already know what your product can do what we need is we have a real world application uh what we want to develop a real world goal we need directions on how

to achieve this goal that's it that's it how you should documentation another way to think about your documentation is like you have this tool and in this case it's a hammer because everything that looks like a nail needs a hammer is a tool you wouldn't use this Hammer to drive in a screw that's not how you use the tool but give a child a hammer and they

don't know what it is used for so they try to hammer in the screw and it doesn't really work so without the instructions to use your tool correctly it is useless so with that in mind and with very limited knowledge at that time I did something so that's the next version of our docs a few months later you already see we don't have this annoying start page

anymore because it's useless uh I also got rid of the starting page after that just say okay if you want to try out our tool and that's the best thing you can do if you want a really fast onboarding take something like gitpod or get code spaces or stack blits if you're if it's possible we use GitHub because it's gitpod because it's not possible and then guide

your user already this is not perfect as I said different problems on different platforms but it's better you can try it out in gitpod that's fast or you can try out the local installation that's cool we also have a a search box here which doesn't work right now because it's local deployment and um I'm coming from software architecture we have a lot of product terminology so I

added a terminology restructure the troubleshooting which is now not General but platform specific uh you already noticed that hopefully you that we restructure a little bit there's an anti pattern if if you think about psychology you can hold Max Max seven things in your head so if your menu has more than seven menu items it gets cluttered some even say it's three so you should aim for

for less and you also see guides is strange because guides is more like a trash bin for every content you don't know where to put what we also did we expanded a little bit our API docs so now we have some asy art we also have a lot of examples and we also have gifts so you know what a specific command does this is already much more

helpful than the version before in the title I said it's uh beautiful how do you create beautiful developer docs and I have a very specific opinion there I think I already discussed with Chichi yesterday if this uh is practical because I think beautiful is not that important to dogs does anyone recognize this art this this where this documentation comes from so some someone configured an engine X

yeah I think that's the most ugly but most useful documentation ever I encountered there's not even a search it's a one pager a very long long pager but if but with very very tone down markdown the Dom is very efficient so you can search with your browser and the cool stuff is I configured a complete reverse proxy with this single documentation because it's so great you have

you you search something like oh and need this custom Arrow page how do do I redirect this you find it you have a short explanation you have examples and you know what to do so my stance is yeah beautiful developer docs cool stuff but actually not necessary but if you want to have a nice example I think I have to Google this let's see uh it's minor

eight right does it work I don't have the password okay I I wanted to show the the empathy platform so you just have to Google it um this also a clean documentation but they have a little bit more design to it and you can drill down cannot show it right now so for me it's all all about developers want solutions they want directions and if the documentation

achieves their goal then Perfect Design follows function in this that's also why the strip docs are cool we we get back to that example you can try out everything on the left in your code and see the effects on the right or almost other way around so you can try out stuff it's very Hands-On documentation and that's useful okay so with that in mind let's get back

to to our docs to version three so as you can see nothing changed from the start page I'm not happy with that because course we need some platform specific things there but we restructured our menu here so now it's getting called getting started so everybody knows what what there is we have some how aski works because sometimes it's interesting to see how a product works and then

we have installing RI don't know what this is I removed it then we have your WR your first in instruction then we restructure to okay what does the user actually want to do so giving more directions so it's UI automation so the user wants to select elements of course so we have element selection and we have different element selections still a little bit too much here but

in the next version hopefully that's gone also we want to execute automations and of course Integrations so this already looks better yeah so the structure of the menu is also important to find things you I'm pretty sure everybody went to some documentation site and you have this endless menu and you think yeah where's the thing I need to find and if you don't have a great search

uh your customer is basically doomed so the next question was like okay now we have this restructuring we have some nice API dogs we trying to guide our developers here problem is our developers are diverse like I already said some come from test automation different different languages they use um not the typical developer more like uh rpas robotic process automation people so is this actually useful to

all of these people and I I see that the problem you can't cater to everyone in One documentation but you can give them directions so this a marketing term segmentation uh as far as I know but I use it here because it it fits so what we did was thinking about and funny enough we had a company Workshop where we def finded our personas or ideal profile

uh and we had four customer profiles three of which we wanted to actually Target with the documentation and that's nice so you and you also and that's what a lot of developers might not want to hear but talk to sales what is their usual sales call where are the people coming from they have all the data you need to actually craft your perfect documentation because they need

they they get to see who wants to have their problem solved with a product so talk to sales sales is it's easy in a startup I only have two guys to talk talk to so I can get the information but it's important to get this information so you can do this segmentation one example I brought before but I think it's a very cool example is the platform

or documentation you have to search if you're just starting out and don't know what to search search or if you're looking for something specific and cannot find a very powerful search but they also have different use cases and you can see it so if you're just getting started click on the getting started if you're a developer cool go to developers developer guide you also have the API

reference which is usually used by more experienced uh users also have best practices and the use cases and I don't know what the platform as kit is so I think this is a very good example of how to do segmentation correctly they know their customers they know they have to specific guides for them specific directions this another one I don't know I and umra what they actually

do looks a little like fintech they also do this so they have explore our apis did you know that most of the apis are actually not used by developers but more than 50% are used by business people they program against apis to get something done so API docs are specific uh for different specific soona they have also how to get started and also a more deeper developer

block so so nice example of a task if you don't want to talk to sales you should at least get your customers user goals and user goals are more Theory but if you put them in practice they're very very powerful because user goals are always rooted in the real world as I said before when I build an ARR examp examp I don't get to say I just

try out a vector store because there are so many out there with their AI hype I just I come there and say I want to build this example this specific example so I have this goal in mind so world and then you get to ask your salese what is your persona what they actually trying to achieve and in our case I wrote everything down they have a

few example user goes they actually they are not that important I would I would say from you say yeah they not not important that's the wrong word sorry not a native English speaker um it's not fascinating when they come to our documentation they always come with oh I want to automate on an Android device that's one user goal or I want to automate a native Windows application

so it's you see a lot of UI Automation and the user wants to automate a native mechos app or a combination of all those three I want to do something crossplatform that's how our users count to us that's what we what we got out of our sales codes and uh all the customers we talk to so this is important information these are your directions you won't go

and say yeah how do I uh give a direction in your documentation on your starting page on how to automate a web browser because that's not what your customers want to see they want to do this stuff and then it becomes tricky because then you have to go deeper into Theory and think about learning objectives and learning objectives have something to do with user goals you can

derive some learning objectives out of the user goals but they are completely different from user goals user goals are rooted in the real world and learning objectives are rooted in intellectuality they are intellectual goals so if you want to uh achieve a specific user goal you need a lot of learning objectives covered so you need a lot of covered and these learning objectives have a few characteristics

they broadly they are sometimes more depending on on where read about it they fall into three categories one is applicable skill an applicable skill is something when we um get back to the Android example the user should be able to connect our software device cool now the device is connected okay that's one step in the user goal and you see where I'm going with this we need

a lot of applicable skill to actually get your user goal across um then they need to do some text selection or some element selection in our case so what do they need a learning objective that tests them what is even there when we're talking about text selection so there are different methods like you say it's a exact match it's a regex match a contains match or just

a similarity metric or some kind of stuff that's that's everything you can do with text for example so you need to be aware so the next category is awareness and we formulated the learning object the user should be able to describe the different methods used to select text you see there's it's not applicable they just know oh there's these methods and to achieve user goal you also

need this uh third category comprehension so now the user knows what to do what what they can do but they don't know how to use it correctly that's where comprehension comes into into place so sometimes you have a long text so if you match for similarity if your OCR is bad then it's hard so you may have to use a regx for example so you need to

know what these different meth methods actually do so comprehend them and put them into place you need all of three categories to usually achieve a user goal there's another thing about learning objectives I always uh find fascinating when I'm coming from software architecture because everything software architecture does is okay we have this modules and we Define how they work together and if you're defining learning objectives they

usually lead to pages in your documentation that are self-contained and not duplicated that's cool from a software architecture point of view yeah note application cool stuff actually and what you can do is say okay so you have this learning objective you have connect an Android device and then you have this learning objective um how do I actually select text and then you can say before you select

text on an Android device please read this learning objective and you only have to maintain one piece of uh documentation one page so it becomes easier to maintain I hope I can I can find the example you didn't do this and it led to uh led to a lot of uh confusion and especially this Android example we always everybody who wanted to automate Android got stuck somewhere

because the documentation was on two different places and it was different on each place because we forgot how to forgot to maintain it yeah that's exactly what what happens if you don't separate if you don't modelize his documentation so with that in mind let's first look at the previous version and say okay where's the problem so we have tutorials so we have a web search on Android

tutorial that's where people come in and we have to prepare something here there's also automate web search yes was it the right I can't even find it so I think it's a flutter sample Android so we have to do do something yeah so Android is Android documentation is completely scattered I think we already solved it here yeah single single device automation multi- device automation yeah so we

have here oh we have here some Android what you have to do on Android and also some mobile automation there's another Android stuff so you see this this these learning objectives are not really modularized and sometimes there there was also duplication and depending on which tutorial our users read they got confused which is not the thing we want so this is the not the last the last

um example the last sorry the last um iteration of our docs but one that is recent yeah 08 Z you can see I got some tiles in here based on the personas I mentioned before so if you're coming now and and see our documentation you don't get to look at the menu you look at the tiles and oh I want to automate Android I want to automate

Windows actually Windows is the most important stuff here because everybody wants to automate desktop applications on Windows if you're coming from Enterprise and have a lot of proxies and lock down machines because they're managed then yes um you have uh Enterprise checklist which exactly tells you what to do if you don't have the permissions contact your it department and all that stuff because a lot of users

in Enterprises are not even aware that there's a proxy you have to tell them so we give them the directions to actually make make our product work there that's very important that's also what we got out of the sales calls um yeah that's that's what we did and we also had a new product here that's okay we restructured the getting started to actually be platform specific so

you don't have to read about Mac us if you're Windows user nice and we hit a lot of stuff so this should so yeah you just use in it now so the dependency stuff that's not important if you're getting started maybe later if you do some uh Security checks on the packages and also the guides got a little bit cleaned up and we hit the tutorials in

the examples and you can see okay how do we automate mobile devices how do you automate multiple devices and that's the usual use cases we broke it down to just two so it's yeah it's Vis so I hope you learned that modularizing your documentation and coming from uh user goals breaking down to learning objectives this not a straight path that's different for every product that's just what

we did here for us it's not completed documentation is always always a work in progress especially in a startup when the go post change all the time yeah um and then you get a better documentation I'm the documentation now is comprehensive and usually if a user asks something I can point it into the right direction and they don't get confused they can can solve it by themselves

if they're capable of enough so how did we built this and this is uh one of my favorite slid slides so you go from user goals to objectives that's what I already said then design follows function how do you build it on the technical side because I wanted to do some uh something in the code in the IDE here and uh I'm a developer myself I laugh

Doc's code already did it U with Arc 42 and asky dog when I did soft architecture and dox's code are are great if you're living in an organization who is mainly consistent of Engineers because it's easy to write if you use markdown it's basically very very simple to write you can get every engineer to follow the rules because logical uh it's very easy to review we use

GitHub you can use skit to review do pull requests do comments everything you can do everything you do with code if you're in an Enterprise environment uh you can even style it like when I worked at uh at the Enterprise company we have hady style guides ah easily covered with CSS and the processor pretty cool you can do versioning so you can throw documentation can bring it

back also also nice thing and personally I don't like Vick who's using a Wiki here oh barely nobody like Confluence some some people ah yeah Confluence Confluence was the was the thing I had to say yeah I always hated Confluence because that's that is where documentation goes to die that's that's the that's the thing every Wiki is like that and that's the problem because everybody can dump

their brain into the documentation and it's not well architectured and the moment you do doxes code you can say nobody pushes to main without a review and it already gets better because someone else is looking at the documentation just because of that our text Tech pretty simple use some standard software like dogosaurus you can use everything like MK dos example and we use linters um for me

importantly the Alex linter which um Linds for profanity and inclusive language and we switched from a spell checker to Pros lenting with whale whale is open source you can use it however you like you can Define there custom rules you have to custom uh terminology and all that stuff you can for example say okay I don't want something like e dog dot in your documentation because that's

more or less like not everybody knows how to do it so you want to have the most simplistic language in your documentation that's what you want and whale can Lin for that that's that's the stuff and let's show how that works in the IDE I hope that's I can make it a little bit bigger you have to install it at least on Mac OS and then you

can Define some rules and how do you led it's like whale and the directory you want to lint and the configuration here is like okay lint every Mark markdown file and of course I put something there the linta can actually find because it be would be not no no that's not what I so it says okay if I say Veil dogs we have our ASI specific terminology

there but it also has a spell checker so did you really mean automation no I meant automation of course and it also Lins inclusivity and then it says yeah bigger maybe that's offensive and as a non-native speaker that's not obvious to me and then I ask I think dma 3 large language model to explain to me why bigger is a profanity and what I should use for

this and it said yeah in some cases it's it's a sexual sexual connotation and you can capture that in pipeline and uh fail the build if you if you like would recommend it because in this context it's not offensive of course but you can Lin for that and it's also only a warning but we CAU caught some very spelling how that how is that uh how does

that work we use a a pre-commit hook it's called husky funny enough husky can also be offensive in some In cultures okay the explanation slipped my mind so you have a pre-commit and say okay I only want to lint for the specific documentation the latest documentation uh you can also there's a GitHub action for it it just checks out the repository deps one and then okay does

the same thing like okay these are all the files I want linted so you get linting for this repository and then that's where the tooling a little bit hangs up uh we had to create a another repository where all the Styles live and what I do here is check it out myself here and um just link it here and then we have this Alex rules and we

also have for example the accept rules where everything we use in our documentation that Bale says as a spelling error or just missing something it doesn't know that's what we want to have here and you can also reject words like easy that's where the thing comes from and basically because that is condescending for our users so if anybody comes uh to the documentation opens a p request

the build will fail and say okay please don't use easy it's not inclusive it may enrage your users and you can put all sorts of specific rules in there so cunda does a great job with this in the pipeline it's always it's also the same check it out use it and we can distribute this rule set over all our documentation even in in readmes check it out

in a pipeline Lind our docs have a specific set of rules we want to follow so our documentation Al always looks the same okay reminded that we only have 10 minutes left so the takeaways what what what did we want to tackle how do we actually architect our documentation to be useful for our users they have a goal in mind they don't care about features because they

evaluated in on your hopefully and they come with a goal in mind then design is not as important it follows function at best nice design is cool but if it doesn't solve the problem useless so first Define your user goals talk to sales Define your ideal customer profile know what they're doing talk to your customers get your community involved uh to find the user goals users try

to solve and then def find the learning objectives as modular as possible so it's easily maintainable for you and support the user goals that's ongoing process because yeah I'm also learning and then last but not least you that's not a must but I love Doc's code especially in an engineering organization because it gives you all those things like the review and you can bring back stuff you

can do linting with all the tools you already know and that's it I didn't do an intro if you want to connect with me do it here sometimes I also live stream where you can see that that I'm actually not the greatest coder but I struggling a lot with a lot of documentation uh now I I have a a sharper eye for documentation so it's even more

funny thank you thank you Johannes now we have some time left for questions and uh do anybody have some in the audience please raise your hand yeah and somebody will bring your microphone one here okay question is you mostly talk about technical documentation but what about business documentation because business documentation is quite related with technical documentation now uh business documentation from software architecture or from business processes

business process and how we develop this business processes how this documentation could live together um I think I'm not qualified to talk about this but the general thing is always documentation only gets read when it's for your audience so the problem a lot of people have is if they're writing documentation they don't want to write the documentation because nobody knows how uh who reads reads it so

I would always ask who is reading your documentation and design it like this that's the only thing I can say about this anybody else uh thank you a small technical question I guess uh it's nice when you do like a pull request and you mentioned the example with like easy being a potentially harmful term um ideally I don't really want to see what's you know bad I

want to see how can I fix this quickly uh do you think it would be possible to also in such cases uh get the context in which for example the word is being used so so that you can immediately offer relevant suggestions uh to fix the problem uh Alex usually does this um sometimes whale does this also when you define custom rules like for example with the

a do g dot you can add a context and then it gets printed out to the console so yes you can do this also you can yeah it says okay this is offensive thanks this is offensive but you can provide the solution for it like say don't use Easy use uh don't use it at all for the the bigger I think that llama three could be added

to it said yeah this is use something like elusive I think was this or like I don't know I don't know what the specific term is actually yes I think we have one more question somebody in the audience yeah I think I might have can hear me yeah uh I had a question between the iterations how did you gather use feedback what how to improve the documentation

and did you measure that it became better like did you have any yeah did you get user feedback oh this is actually better how did you do that once I use it myself extensively because I also document for myself I forget a lot so I I knew okay I I can information um but it's it's always about qualitative feedback so we have this thumbs up button I

think can we see it some here so we can thumbs up thumbs down yeah that's not not clicked often but actually we ask our customers who bought the product and ask them and really talking to your customers that's that's the key qualitative feedback because often the customer say yeah I try to set up Android and it didn't work I don't know what this step does and then

you get the feedback sometimes also the customer say yeah pretty easy also yeah anybody else don't hesitate just hand yeah no so we can move to slide questions we have few of them there and few minutes left uh first of one you mentioned interviews with sales department to learn about more user needs did you also use another data sources for improvement opport unities so usually want to

have a community for your product so that's where usually develop Advocate gathers a community um it's not okay it's not uh too big our community um I usually talk to customers who are bought our product and they have some developers and I usually try to get in contact with them not the one who bought but actually who's using it yeah and also we have analytics of our

product and we see if somebody tries something five in five different ways they're struggling with a specific thing like selecting a specific text and then you can also track okay they visited a documentation on this part and they're still stuck so at some point you could reach out to that customer and say hey you're still stuck what do you need to succeed yeah another one how do

you properly manage docs connection to app SL platform features so that if features change or deprecated nobody forgets to update docs Doo Oh I love this question every time I do this this docs talk I haven't an answer for this and it's also the same with software architecture the best thing you can do is provide a Cher task for it documentation in your process so if you

create something there's a a task or attached for documentation the next thing you can do what we also tried but works as good as you you try it is to do a monor repo where the documentation lives together with the code that's also some something so if someone reviews you have good review practices which comes to process then you see okay there's some some change but there's

no documentation for it and then you can say yeah that's a acceptance criteria documentation but basically what only works is it comes down to process so how well is your process defined and how well are your following the process I this this disconnect is really hard to to get solved actually there are a few more questions but we really out of time so uh thank you yanas

Applause for him