 Hello, my name is Andrew Burden. I am a technical writer for Red Hat and for the last about four years I've been working on predominantly Emerging technology, documenting technology in the container space specifically. So what do I mean by tech, emerging technology? Well for this talk What I mean is working on something that is pre-release Something that the documentation especially starts with kind of nothing and you're creating something Pre-release technology like Kubernetes maybe four or five years ago kind of thing Something that is at the frontier And rapidly evolving and pivoting changing very quickly The landscape where a feature might be obsolete by the time it's released and certainly by the time it's documented So I'm going to use the term just technology Throughout the talk and please replace that with product project and you know, whatever is For your circumstance And whatever you call it's that breaking of ground that first one or more releases to make something out of nothing In a maelstrom of chaos and stress and few if any dog systems in place to lean on And before we kind of get to that that interesting part of it I want to kind of have a quick look at like a hypothetical life cycle of how we get to that point Here we go A technology is born from the hearts and minds of a single or a small group of developers And through infancy it attracts more developers It grows and maybe sprouts and features and the documentation here if it exists Typically focuses on helping developers contribute to the project By necessity you need to have strong foundational knowledge in order to be able to contribute And the dogs reflect that It shifts into adolescence And this is where things get interesting Like a team manager it grows quickly and it changes quickly Teams form features evolve the technology pivots Documentation then is worked on by their growing list of developers may be independently handled by each team And the doc set evolves it no longer focuses on contributed docs But also on user docs Because it's gotten to a point where you have the desired outside users able to come in and use the technology It's not just contributes But there still remains a developer mindset In adults And you still need a developer mindset to use the product because it's still in its adolescence And the users still require some foundational experience in order to be able to get you going And there's docs Apache And it's not because of anyone's fault and I really don't want to like I'm not playing a blind gamer and I don't want to feel bad. I kind of want to do the opposite In fact, if you work in upstream documentation Like It's great You're a bit of a legend And It's because it's written by a variety of people with a variety of experience with a variety of time constraints Probably in a variety of languages But there's a general inconsistency and incompleteness in the docs that and it becomes clear that someone needs to focus on the docs Particularly in order to bring them up to snuff It's a work Because the adolescent technology wants to become an adult in my analogy it wants to grow up Now in a company like red hat Or a large enough foundation like cncf or safe or something You might have a requisition for a specific docs asset And this is the beginning of what I call The lag period Unless there's someone who can immediately jump onto that technology right away It's going to take time to find that resource and it might be days weeks months All the while the technology is growing and that docs problem is expanding And that coordinated release has also meant the developers are less likely to be focusing on writing the upstream docs You know, they're trying to get their code ready for release and docs becomes less of a priority So when the docs person joins They have to onboard with everything design and create the doc set and catch up that lag period of the upstream docs All the while staring down the barrel of the release Which in my experience is one month to two months And in that one to two months you're coming back to cover the following The scope and scale of the release but from a technology and a doc's perspective You establish the doc structure. What's going where it's going to live Other details of the deliverable And that can be heavily influenced by the constraints of what you're working with and on Um your schedule, it's a no-brainer But you need to familiarize with the code freeze the docs freeze the reviews Etc Understand the hard and soft time constraints in order to work with them and have a rudimentary sense of stability because there's no point Documenting something that's just going to change next week. So you're going to know your windows You've got to meet with relevant people. There's not be joining a few daily scrums weekly scrum of scrums free planning p.m Meetings onboarding progress reports demos. What have you it's good stuff. It's really valuable Um, but it can weigh down your calendar time is precious. So you got to figure out that signal to noise ratio really quickly You're going to learn the technology and the underlying technology if it's required. Now, this is pretty obvious But what might not be obvious is the scale and the breadth of that understanding Um familiar design and write good documentation I need to have a solid understanding of the whole thing All the relevant moving parts in order to understand how to structure the content and how to get into the mind of the user so that I could provide enough information that they can confidently use the product But not so much information that i'm getting in their way. I don't want to push them away from the product That's not my point um, and it's a fine balance and the only way that I find that I can do that is to Trudge through the information Which is in many different places and some of it doesn't even exist Aside from the the the codes amount of that design docs Or maybe just in the heads of the people who are developing it because it fell into that lag yet I'm not so good But also you need to deploy the technology has no better way to learn than to do Now this can be a huge time sink. You got to find the hardware and maybe sort out networking storage problems Um, uh, you know if you're installing if it's An add-on or an peripheral technology on something like kubernetes or open shift You need to install that get that working and then installing the technology on top of that Which maybe still having its installation method kind of figured out And you spend hours trying to debug what has all the appearances of the network issue when it turns out There was a bug in the installer all along So it's a lot to be done in one month even in two And the ground moves a bit under your feet and on top of that you're Designing and creating content and having it reviewed and raising bugs and going back and forth and review A lot to do time is precious So what I'd like to cover now are some uh pitfalls that I've identified over the years usually by falling down them And this includes some advice on how I think you can avoid them And I came up with a better name for this talk two minutes ago And it's things I think to help you do docs quick And it doesn't have a slide Here we go. Oh Oh, no, that's not my slide Well, it was um An art depiction of the wall in gamethrines, but anyway Um, there was a lot of information coming at you and hopefully I'll come at home There's a lot to do and to learn and to establish your starting point and my take home advice is Take notes. It's it's pretty obvious. I know but take notes Write them down and take notes about your notes I think that I take a lot of notes and then invariably down the track. I realize I should have taken more notes I always wish I'd taken more notes and I've never ever thought I should have taken less notes Take notes of meetings take notes of successful builds unsuccessful builds copy paste snippets of your ISE conversations and dislike Put them together and modernize them organize your notes. Don't simply add to your own information or be organized with your notes All the things I think that I remember while I'm working close to technology, especially to release that or the docs Six months down the track. I've got no idea. I'm dumbfounded I look at things I I recognize a reason for the inconsistent, but I don't understand it myself And I just wish I would have left a note in that leave breadcrumb trials for yourself and for others You don't know who'll be working on it in the future. You might be lucky enough to get some new teammates Maybe someone, you know, maybe you've handed over to someone So be good to them and your future self. Take notes. Take notes about notes. I really hope I'm driving this home Leave notes in your docs. Write good commit messages. I used to write All the time the dumbest commit messages. So I worked just by myself and I thought it was hilarious Well, when you're in a pickle, it's not so hilarious. So I work on a team And I still write dumb commit messages, but I'm happy to say I write a lot less of them The technology is growing quickly teams are emerging. There's a lot of excitement Features being planned and added, but they're not going to make it to the release with all of their bells and whistles So they get staggered over a few releases next release next release Which means all the conversations and the meetings about that feature also bounce back and forth across Multiple future versions until you lose your head because until you know what you don't know at that time It just sounds like it's all going into one version in that meeting And without the systems in place, it can really easily become lost in it So yes, you do need to know that information eventually, but not when you're pressed up against the release date for 1.0 And be aware too that this problem can exist for multiple versions. You think, you know, that's just a 1.0 problem It's it's going to be better next time and that happens again in 1.1. It happens again in 1.2 My advice, I actually don't have really any advice All I can say is that clarify when you can Ultimately the the the solution the best thing to happen is it's across the whole team It's it's part of the joy of documenting emerging technology and working in this field When the processes mature a bit and things aren't in 100 mad dash mode You get that kind of sense of clarity Administrative overhead is the answer I'm sorry to say and in version 1.0 that might not exist because they've got pushed to version 1.2 So take notes again Clarify the best defense is a good offense and the best offense is organized It's not necessarily a pitfall and I talked about it earlier, but I also can't stress this one enough Yes, it can be a time sink, but it's really really important especially in this kind of area where there's a Very significant sense of genius to it all The first emerging technology I worked on was deploying middleware products as applications in OpenShift 3 And I came to the project not knowing anything about OpenShift middleware or Java And to prepare myself I read up on the docs the internal docs the upstream docs for the existed Follow all the mailing lists I read everything I could I watched a couple of the short demos that the devs had Quite awesomely delivered to me But even with all that information I still only had a partially filled out skeleton for my content I managed to get OpenShift running, but the pods for the app never managed to survive deployment And in five days before the release Friday afternoon, I got access to a developer environment and over the weekend interacting with that technology everything clicked into place on Monday I was able to draft up the doc what's a live demo that night Which finally made sense to me for the first time and then bash together the whole document get a reviewed merge published by Wednesday The information is one thing, but it wasn't till I could interact with the technology as user zero But I had the necessary context in order to understand it in a way that I could then confidently document it for the user So access to the technology is very important and it comes in a few flavors There's the interactive kind. This is the instance that you deploy yourself As far as writing user focus documentation being user zero is the best. It's amazing It requires the process of deploying and Installating installing from scratch I'm a words guy hitting all the prerequisites along the way and then using the environment You know, what do you do first second third? Yadda yadda yadda. It does have a downside And that's that it might be 10 minutes It's time continue to get running. Uh, by the way, so it's better to get someone else to do it The downside then is that you don't get to have the installation context Save sips time. Just don't break it Not interactive so the live demos They're great because you can see the environment ask questions clarify get the presenter to kind of go through the procedures that you need Downside is that you can't necessarily repeat it at a later date So you need to know all that information all the questions to ask ahead of time Can't have any unknown unknowns, which is a problem Again, it lacks that visibility against the installation and setup We can have a demo a video of the demo, which is the same except You don't want to get that controlling interactivity with the with the demo itself. You can ask questions, but not in real time for CLI ASCII demo is ASCII cinema is really awesome You can copy paste your way through a live terminal. It's nice and slender The downside is that it's silent. So if the presenter is particularly awesome, they can add comments as prepared comments to narrate the process and the logic One thing about demos is that Screenshots really handy to condense the information. You get it can then also capture the UI to look at later It's a lot easier to go through small amount of screenshots of the demo then That is to go back and forth a long video Just think twice about before including screenshots in your docs In this world, things change really fast and the maintenance cost of screenshots is often far greater than it's worth Don't know where to start or you're stuck Installation process is still being fine tuned. You can't get the product working The demo makes sense to everyone in the room except you. Where do you start? What do you do? My best is to Create a skeleton and give it to life one piece at a time Luck in any project you're going to be starting off with the MVP the Nim and Byron product Use that creator table of contents leave gaps for your known unknowns The broad view makes it much easier to view structure and negotiate logical gaps than going through when you've got bits of content everywhere Like how can you add a resource to a cluster if it doesn't exist in the first place things like that It also helps to really focus on the the user journey Rather than trying to reverse engineer stories from existing features and then trying to make them fit and shoot home into a doc structure This happens both upstream and downstream docs things are being developed Everyone on the team seems to know about them and be aware of the importance to them And someone started a doc somewhere but what happened to it and then it's just it's lost Um, this typically but always and again, I'm not here to make anyone feel bad But it typically stems from the development workflow And my advice is to be really strict about including the docs in your workflow Issue stories bugs. Does it have a docs impact? Does it have a doc doc component? If there's a change it needs to be tracked Either in the upstream docs or the down or probably both The story can't be done unless docs has been nacked or act and tracked And then oh write that down on slide So that's where this is supposed to be So the last couple of weeks Really quite mental Pretty wild and as the process narrows things get crazy everything. It's really is get lost So my solution it won't be a surprise. It's to take notes to make checklists Yep, more notes What needs special attention in the review? Who is Your review team who do you need to ask to review x y and z because the last minute you don't want to be finding that information out Where's the release notes process find out ahead of time and then put it into a list so you can look it at the end And it just makes your life so much easier have a pre-release or a plea for a pre-flight checklist These kinds of things, although very helpful in version 1.0 Far more helpful in version 1.1. Think about the future Put into that Pre-release checklist all the little things that aren't going to have a bug or an issue to track them things like changing version numbers Changing the package names making sure that the cli commands are all still relevant The syntax hasn't changed under your feet if you use screenshots has the ui changed probably So things change really quick and they obsolete really quick I've documented things that were obsolete before it out put on a note. It's like This has been obsolete I think it's especially true for upstream docs. I think like github is filled with ebripo's that long ago at guru They're supporting docs and happens to the best of us and because the information management is really hard and it's time consuming and My advice is to audit People don't like to be audited But docs love it In fact, they thrive on it Bugs and issues are valuable, but they're reactive by nature and once possible audit your docs Factor into your spring cadence and post release Workflow identify your gaps target your updates systematically work through the content and then do it again and again add infinitum um, so the product i'll work on at the moment Can tenant native virtualization docs. We've just had next week a little old or we'll have had a release and Following up we're going to be planning in on auditing our storage docs with our storage team It's like the ship of these years the component the components have evolved to the point that the structure that once made sense is no more and No one no longer knows where the gaps are So we're going to do a nice big audit And if your team grows if you're lucky enough to have a docs team that is getting new people Have the new person go through the full doc set from start to finish as part of their onboarding experience Raising questions pulling out your consistencies and gaps Fresh eyes are a rare and powerful resource If you already do all of this You're you're a legend and you're making the world a better place by including its coherence Ultimately though Do what you have to do, you know screenshots might have a short shelf life But they're also really really useful in early version documentation Merging technology is by its very nature new And the ux leaves a bit to be desired it'll get there for the screenshot is a good stop gap I tend towards end-to-end walkthroughs starting with installation and ending with creating and using resources I find it's very useful for new products Um, but a small can be captured in you know 12 to 20 steps It's the document version of a live demo. It takes the user from starting Literally nothing and then leaves them with the technology in a state they can then play with Which I think is the point in this kind of fear But it's also unsustainable and as much hard work and love I put into it Ultimately it needs to be shredded because it becomes unmounted unmountable And I've totally run out of time. So I'll just leave you with this little thing Emerging technology is challenging and documenting it is difficult But don't take it personally think of it like a teenager It's still finding its place in the world what it needs is love And that love is best displayed through patience tenacity thoughtfulness and raising a lot of bugs So good luck out there. Thank you very much for listening and I I hope it's up Oh, I've got I've got two minutes for Q&A panel. Yes What would be your advice if some of the technology you're working with is hardware or it's not as easy to replicate Again and on your system beg borrow and steal Yeah, that's that's all I have for yeah All like old laptops are working companies are getting old laptops and building a cluster out of that and trying to get stuff out of that or try and get money for cloud services I was thinking of things like with like drones, for example, where it's not like a laptop or a computer system Like actual hardware hugger Beg borrow and steal man Joshua It did okay, that's awesome. I was no sure you could listen to that tool for two years as a tech writer and just like They could be like the soundtrack for your career Thank you very much. Anyone else? Thank you. All right Yes Thank you very much. All right. Have a good sleep though. Thank you