Generate More Revenue in IT Architecture Documentation with airSlate SignNow

How to create outlook signature

[Music] i'd like to begin by acknowledging the traditional owners of the bungeeland land on which i'm giving this presentation today and pay my respects to their elders past present and emerging i would also like to acknowledge that this land which i benefit from occupying was stolen and that sovereignty was never seeded by the bungeeland people so i'm going to start with a little bit of a humble brag but i just moved to australia's gold coast you might remember the gold coast from when tom hanks got covered 19 about 4 million years ago anyway we've moved to a relatively nice area with a lot of development going on and most of these big development sites have advertising up around the construction enticing people to come and buy an apartment or two and all these new places have a few things in common they all have a stupid aspirational name like esperance or athena this one that i took a photo of for you is called delta which i'm certain they're now regretting but they also all say something about architecture architecturally designed one says this one this delta one says architect design homes to suit your lifestyle so i'd like to have a think about what architecture means in this sense clearly the developers of these properties are relying on you thinking that having an architect design your home makes it a bit fancier when in reality most of these projects are just apartment buildings i've lived in a few apartment buildings and they're mostly just tiny boxes stacked on top of one another but if we dig past the marketing words we know that an architect is the person who designs the building they don't choose the location go out and buy the materials or do any kind of building plumbing or electrical work they don't choose which furniture to put in the home what the kitchen cabinets look like or pick the carpet they are purely about design picking the shape of the house the layout of the rooms making sure it suits the area it's in and the people who are going to live in it and presumably about getting a spot on ground designs or a tv show like that so can you have a home that hasn't had an architect well one of my guiltier internet pleasures is to browse bad real estate photos and the way i see it is that these are the result of homes that haven't had the benefit of an architect or maybe they did have the benefit of an architect but it was so many renovations ago that the architect might have wore mission brown flares and a peace sign necklace and in most of these atrocities you'll notice that the fixtures and fittings are often quite nice like this perfectly reasonable bathtub or this quite lovely chandelier the thing that's gone wrong here is not the construction or the furniture or anything like that it's the design so to bring this around the long way to documentation you can think of the words you write as being like these kitchen drawers perfectly good wood cabinetry nice chrome handles if only they designed them in such a way that people could actually use them and that's what this talk is really about i know you already know how to write great words in the best order i am certain that you can craft a procedure that makes grown adults weep with its elegant simplicity and i just know that you can come up with the perfect title for every document every single time but none of that matters if you don't have an architect if you're starting from a completely blank slate then lucky you can skip this step but i'm betting that most of you already have something written down whether it's new content or older than time itself the best way to work out what you need is to make a critical assessment of what you already have even if what you have is the carpeted toilet of technical documentation now this step works equally well if you're new to the content and need to wrap your head around it or if you're a bit too familiar with it and you need to try and see it with fresh eyes the best way i've found to start with a long hard look at your content is to create a content map how you do this depends largely on how much content you have if you have a few hundred pages and you don't want to go too deep into your hierarchy then you can probably just create a table in a document if you have say a giant wiki that you're trying to categorize start with a spreadsheet you could potentially go the whole hog and set up a database if you really want to spend time on this but in most cases that would probably just be overkill so this is a content map i did when i started my current role and if we zoom in on the first page you can see i've only looked at the top three levels of the hierarchy at least partly because that's where the bulk of the content was so we have the top level second level and third level or page title we have a url to the page and the general content type of that page now i'm going to come back to content types in a minute for now though you can already see patterns starting to form just by zooming out now i appreciate this is blurry that was done very much on purpose you should be able to see that we have one huge top level bucket that contains most of the content and while the second level headings are more evenly spaced there's still one that's much bigger than the others you can also see that the smaller top level headings don't have a second level heading most of the content sits higher in the hierarchy than in our big top level bucket so that's something we'll need to come back and look at now content types are something that probably most of you have come across and there are several different ways of categorizing content but my favorite one is the dita or dita model and that's mostly because it's the simplest understanding to explain basically there are three different content types concepts tasks and reference if the content answers the question what is it then it's a concept concepts are usually prose paragraphs that explain what something is or how something works if the content answers the question how do i do it then it's a task these are usually numbered steps in the form of procedures and then if it answers the question what else do i need to know it's a reference this is usually a table or a list of things that you can look up to find out information such as what a particular command does or a list of options now good documentation should have clearly defined sections of concepts followed by tasks followed by reference and so you can probably start to see at a glance where my biggest issue was most of the content i had was mixed it had concepts interwoven with tasks and tasks followed by more tasks without any concepts at all and very little reference content this is a giant red flag beginners need lots of concepts and experienced users need to be able to skip the concepts and easily locate tasks and reference information when it's all mixed up it just becomes difficult for everyone so now that you have a content map drawn up and you can already start seeing some of your initial problems you need to turn around from your content and have a look at what's on the other side your readers the first thing to do is to really think hard about who is reading your docs the simple answer to this is our users but that's actually a bit of a cop-out there's a reason that most technical writers use the term readers rather than users for the people who look at our documentation it's because users use software and readers read documentation and while that venn diagram overlaps it's not a perfect circle your readers are not always or sometimes not even mainly your users depending on your product you may find that sales and support staff use your docs more than end users do which is the case in many professional contacts in the open source world you'll probably find that people read your docs to determine if they want to be involved in your community or if they want to use your product in their own project or maybe they might want to fork your project for some reason these readers cannot necessarily be considered users and it's important that we write documentation that is appropriate for those readers as well now i'm going to tell you a secret no one curls up at night with a warm drink and a great technical manual so if that's the case why do people read docs generally speaking it's because they want to achieve something to put that in less abstract terms you need to work out what problem your reader is trying to solve there's a common quote from business school that says something like people don't buy a drill because they need a drill they buy a drill because they need a hole when it comes to documentation though you need to go a step further and ask why do they need the hole let's say my friend alex is at the local hardware store looking at drills what kind of advice would help them there's a pretty good chance that when alex woke up this morning they didn't think you know what i don't have a drill i should go out to the hardware store today and buy one what is more likely is that they woke up this morning and thought something like oh i should hang that picture on my office wall or i should a bed over the staircase so the content that alex needs is probably not called how to choose a drill the content they need is something more like how to beds in unconventional places this is an important distinction because if you get it wrong your readers won't know if the content is right for them or worse they won't find your content at all now it's really easy to sit around and have a think about who the readers might be but it's even better if you can go out and find out for real this isn't always going to be an option for you depending on how much time you have available for research so i would definitely recommend that you do as much of this as you possibly can but don't beat yourself up if you simply don't have the bandwidths to do it all the main thing is to try and get in contact with your readers in any way you can my preferred method is to start with a series of one-on-one interviews with people you already know if you have a community around your product or company you can usually reach out to your top contributors and users pretty easily if you're in a larger corporate environment i would start with sales technical account managers and consulting staff you can then use the information you get from these interviews to create a short survey to send out to your wider audience if that's an option that's available to you now this research serves a few purposes the first reason is that you get direct feedback on your current docs there's a really good chance you'll find out some truths about your dogs but it's even more likely that you'll have some suspicions confirmed about the pain points which is great because now you have data to back up why you're making changes and a much better story to tell about the improvements but the second reason is a little bit more long term you might not get any advantage immediately but in the weeks and months to come when someone notices a problem in a document they're more likely to think oh hold on someone was asking about this recently who was that so it actually builds engagement in the long term it's also really important to understand what readers actually want rather than what you think they might want in my previous role the developers kept telling us that we needed more quick start information but when we spoke to our readers they all said they wanted more explanations of how things worked not just step by step procedures so both of those are about getting started with the product sure but in terms of the content we actually needed to write they were quite different by the same you also need to find out if readers actually want what they say they want one piece of feedback i once got from a reader was to stop moving things around and this was really interesting to me because when i dug deeper into the problem it turned out that people found the documentation so difficult to navigate they were saving hard links to the content they needed so if we moved things those links broke the problem was not so much that we were moving things around but they couldn't find the stuff they needed within our docs in the first place in the end the solution to that was to improve the navigability of the site to implement a really good site search mechanism and to get more consistency in our section headings and procedure titles so it's clearer what was in each section in short the answer to stop moving things around was to move things around a little bit more a lot of technical writers like to do a user task analysis to work out what content needs to be prioritized you can spend a huge amount of time doing these properly but i really don't recommend that you do you don't need to go into too much detail this is really just a way to validate what you probably already have in your head by now so to do a really quick and dirty user task analysis you need to start with an idea of who your readers are and the things your readers want to describe the lists don't need to be exhaustive but you should be able to group most of them into some broad categories that cover the spectrum of readers and tasks so if you think about the reader types first the way you categorize your readers is entirely up to you but sometimes the best way is to start by thinking of a beginner an intermediate reader and an expert or depending on the kind of product you have you might think of an ordinary user a system administrator and a support person your three readers should probably be interested in different parts of your product they will be trying to do different tasks and they will need different levels of help from your docs don't be afraid to let them overlap a little bit but try and make sure you've covered most of the options so in the example i've got coming up for you i've used system administrators sales and support but you could easily include developers hobbyist executives or any number of others so let's have a think about what our readers are trying to achieve for each of your readers start by thinking about how they might begin what's the very first thing they might want to do let's assume that they managed to complete that first thing without any trouble what's the second thing they want to do and when they've completed that what's the next thing again you don't need to be exhaustive here but make sure you cover the big ticket items things like installing configuring troubleshooting that kind of thing so once you have those things you can put them in a little table and work out how likely it is that a particular reader will use the documentation to do each task if you put the reader types across the top of your table and all of the tasks down the side you can get a really cute little matrix that looks something like this obviously this is only the first few lines but i'm hoping it will give you the idea you can fill out each square on the table with the likelihood that each reader type will use the docs to do each task now note the really important thing here you're not asking if system administrators are likely to do a product installation because of course they are you're asking if system administrators are likely to use the documentation to do a product installation the answer to that is a little trickier and it depends on some things like how easy your product is to and how often a system administrator might need to do that task so when you have all the boxes filled out you can do some simple maths score a three for high likelihood two for medium and one for low likelihood that gives each task a score the higher the number the more critical the documentation of this task is so in my example here you can see that product research scores are six because it's only really important to one group but managing clients scores nine because it's important to everyone that means we know we need to spend more time and effort on documenting how to manage clients and we can improve the general product info later on now the highest scoring things in your table are called the critical paths the items with the highest critical path score is the content that is most important for you to write all of this doesn't mean that the lower ranked things aren't important of course it's just about finding a place to focus if you find that your focus points are not adequately covered in your existing docs then you have an immediate start point so by now you know what content you have and you have a pretty good idea of who your readers are and what kind of content they need so now we can take a look at the structure of the docs and work out if the way things are organized now matches what it is our readers want generally speaking humans have a tendency to put things in hierarchies so you will probably be facing a documentation suite that looks a little bit like this unfortunately hierarchies like this work well for when we have a bunch of content and we need to organize it but they don't actually work very well for when we need to find something to demonstrate i want to think want you to think about when you last moved house i've obviously just done this recently so i can tell you that what i did when i got to the new place was i started unpacking boxes and boxes of stuff so you pick up one thing and you put it somewhere that seems reasonable and then days later you're still wandering around trying to find it i ended up worming out two cats a full week late in the month after i moved because i found one cat's medicine in one place and the other cat's medicine somewhere completely different after three days of searching so putting things in a reasonable place is a very different skill and uses a different part of your brain to finding things to get this back to documentation you need to think about the different methods people use to find your content are they coming to you directly they might type docs.yourcompany.com into their browser they might search your company docs or maybe they're searching how do i this thing or even what is this thing when they reach your page what page are they landing on are they landing on the top level page of your hierarchy or some page deep in the content and then perhaps the most important question where do they go next do they search for something else on your site do they use a navigation menu to click on something else or do they get bored and click away to facebook one of the most important things i noticed when i was analyzing the documentation at time scale was that we had several methods of navigating the docs but they all relied on readers already knowing what they were looking for this would be fine if we were catering only to experienced readers but we knew from research that we also had a lot of brand new beginner readers and we also had a lot of content already written that was tailored directly to beginners in the form of tutorials and getting started information so we needed to make sure they were able to find it because our product has quite a few unique terms for features it was doubly important that we didn't just assume that readers knew what those terms were or what they meant we needed to develop a way of navigating that not only allowed people to find the content they knew they needed but that could lead them to content they didn't know they needed basically we wanted to guide readers from a place of understanding or i need to know how to do this thing to a place of discovery or i didn't know it could also do this other thing this is an important step because often readers know what they want to achieve but don't know the words to describe that thing or use they might use different words to what we might use so from here we get to a step that i like to categorize as using your thinking brain hopefully the analysis you've done so far has led you to some natural conclusions that are now just waiting for you to express them fully but even if you're more confused than ever you can start methodically working through some ideas how do you need to arrange your content to make it easier for your readers to achieve their goals what technologies do you have available in terms of automation and organization in my current role we decided to significantly flatten our hierarchy and implement some intelligence in the form of keywords and related content whatever your thinking brain has come up with it's time to write all your brilliant ideas down even if they're incredibly unrealistic write them down anyway we'll work on cutting them down to size in the next step so this step is what i call an implementation plan and it's where reality settles back in and we decide what's actually feasible and in what time frame this is the point where it's really important that you have some management buy-in on your overall plan so you might want to make sure you've shopped your initial research around the company a bit so that this doesn't all come out of the blue for your manager the first thing to do is to work out what resources you have that's people time and money these work in the form of a project management constraint triangle which i'm hoping you've seen before if you don't have much time you'll need more people to do the work and more money to cover things like outsourced contractors or ready-made software or tools if you don't have a lot of money you can compensate by having more people to do the work and expecting it to take longer if you don't have a lot of people you'll need more time and money the next step is to determine what your minimum viable product is that's your starting point it's the smallest piece of work that can be done to achieve some benefit in most information architecture projects this is usually a small reorganization of existing content or adding a small feature such as site search from there you can work out what your next level items are more features more automation better metadata for seo improved content right up to complete rewrites tool or language conversions and completely new content now you get to pick the things on the list that you can do within your constraints now as a side note it's okay to be a bit disappointed at this stage it's very normal to have spent a bunch of time doing the research realizing exactly how much better it could be researching the amazing things you could do to make it better only to have to come crashing back to reality when you realize you can't possibly make it all happen mind you from personal experience i can tell you that if you do get approval to implement everything you suggest after that initial rush of approval you have to face the fact that you're about to embark on a massive project and that can be incredibly overwhelming too there are no winners in this game so now that you have your implementation plan i hate to say it but you've got to put the hard yards in and do the work i have other talks on how to manage big projects like this so i'm not going to go into that kind of detail here but if anyone is interested in how to manage that kind of thing you can check out this link on this qr code for a relevant video i'll just give you a second to pull your phone out and have a go at that okay one final note that i want to make about this process is that it's important to measure your success this starts right from the beginning if you have done your planning properly including things like your content analysis then you have a good starting point for later on being able to measure how things have changed it's also a great idea if you have the ability to be collecting data wherever possible especially if you can start before you implement changes it gives you a baseline for measuring for example if you define early on that one of your measures of success is going to be improving the dwell time on each page you need to know what your average dwell time was before you started so you can measure the improvement after your changes and a final caveat is that you might need to be prepared to have your ideas challenged it's entirely possible that even after all this research and planning you implement a new design and it just sucks design and architecture is more art than science after all this building won an architecture award and sometimes you might just try things out and it just doesn't hit in that case the most important thing you can do is listen to what your readers are telling you either directly through feedback or indirectly through their actions on your site tweak things roll things back if you have to adjust as you go and keep gathering data unlike buildings documentation architecture is constantly a work in progress and that brings us to the very end i just wanted to add that i work for an awesome company that lets me work on really cool stuff like this so if that's something that sounds like it might be interesting to you then you're in luck because we're hiring grab this qr code to go and have a look at our careers page and on that note thanks for listening be kind to each other and i will catch you live in the q a after this you