Streamline Lead generation qualification in IT architecture documentation with airSlate SignNow

How to create outlook signature

a good morning my name is Paquita and I like creating documentation and was not always like this actually I think most of the worst skills I possess today still from clippy's times as well I guess are from times when I was actually writing large documents probably in hindsight read ascribing a lot of stuff I wrote in code and human language but I haven't attached word in months and the last time I touched it was not for software documentation so I do documentation very differently today but still saying that I enjoy creating documentation feels a little bit like a secret confession because there seems to be a bit of a stigma attached to the topic especially in the era of agile development and I think a good visualization of the stigma is this this is an internet search for software architecture diagrams and another thing that represents this stigma for me is this is a picture of just two pages of the table of contents of a 500 page book on documenting software architecture and it contains words like templates release strategy for documentation and architecture document and some of these words maybe make some some agile developers shiver a little bit but so what is agile documentation then and this book had a 2011 second edition and the epilogue had four pages on agile and they also reprinted the four value statements of the agile manifesto and and one already took us through them yesterday so I of course want to talk about this one that we value works in software over comprehensive documentation because it seems like in a lot of places this has led to people saying oh we're agile we don't do documentation we don't have to do it so you might hear developers say things like Doc's are outdated anyway as soon as we create them so it's a waste of time or our code is self documenting or documentation like what UML diagrams but on the other hand documentation seems to be on all our minds just yesterday I think half of the talks the word documentation was mentioned as a sidenote and as a lead developer or as a software developer on your team you might also say these things but at the same time you might be thinking these things the team needs to share a common understanding or I just heard Ellis explain that complex thing again or why did we choose technology X again back in the day and of course as Anton awesome also mentioned yesterday the intention of the manifesto self-raising is to say that why there is value in the items on the right we just value the items on the Left more so while there is value in documentation we value working software more and we definitely value working software more than comprehensive documentation like those work documents I used to write so a software documentation basically comes down to describing our software and also recording that description so that other people can pull it up when they need it and so it's for like all kinds of different users other stakeholders in the company other developers our teammates and it's actually quite a vast area so we are describing what our software does what the structure is how to use it how to build and it so it's far too much for a 30-minute talk so in this presentation I'm going to focus on how we describe technical aspects of our software's are not necessarily how to use it and how developers use documentation to communicate with each other in a team and also with some affairs direct stakeholders so I'm not going to go into API documentation or stuff like that and I'm also focusing on documentation on a higher abstraction level so of course our code can also better describe our software and our tests but I'm going to focus on things where we draw pictures and write stuff we actually write stuff down and record it so how much is just enough documentation then and where are you on the scale are you maybe on the left hand side where you prefer to or maybe you're dealing with a code base that doesn't have any documentation at all or you have that self-documenting code that describes your software pretty well or maybe even tests that are nicely readable less specification or are you on the other extreme of the spectrum where maybe you even haven't diagrams that have one box for each of the classes in your code and/or you're somewhere in between and how do you find a good point on this scale of course like so many things in our profession unfortunately there are no exact rules or definition for this what is the best point it all depends but whenever you're looking to balance things out a good way to start is always to think about the value the purpose why you're creating something without immediately jumping to the solution and thinking about the diagram but thinking first about why am I doing this because one reason that's definitely not a good reason to create documentation is just for the sake of a process and it's actually often also a sign that the process owner maybe doesn't trust you so they actually want to have you write everything down again so they can see what you've been doing so I want to go through five of the many different reasons why documentation can be valuable why I find it valuable on a software development team and give you some examples for each of those so the first one is to use documentation to create a common understanding in your team and some of you might have seen some variations of these pictures I'm showing now so we're often thinking we have the same understanding we have a common understanding of thinking of the same thing but then actually when we when we take that out of our heads put it on a whiteboard or on a piece of paper and talk about it then we often realize oh it's actually different and we need to come up with this business common picture and then we can all work based on that on a bed based on a better understanding and literally you can do this exercise with your team so you can maybe break up into smaller groups have each group maybe come up with high level descriptions of what you're doing then present back to each other and find the misunderstandings and complement each other's understanding so that you have a more common direction afterwards and then you can put these high-level pictures up on what I like to call the team's wall of common understanding so it can be very different what's on this depending on your project but one thing I like to do with this is to have a space constraint so if you actually have the luxury to be co-located and you put this on a physical wall you could for example say I'm going to take six or eight a4 sheets of paper and I'm not going to put anything more up on this even if you have a very large system it doesn't necessarily mean it makes sense to put more of the stuff there because we can only keep so many things in our head right so on this wall then you put up everything that you believe everybody on the team should know about the software and maybe even know without having to think about it too much and then the other contents depend on the on the project so you might have systems overview with dependencies or components or a text like overview if your environment setup is very elaborate you might want to put that up if it's really easy to derive from just looking at your bit server configuration maybe you don't put it up and things to look out for that may be worth putting on this on this wall is things like what are you always explaining to new joiners in the first few days that they join the team or what you often need to explain to stakeholders coming by when you're trying to walk them through a decision or what terms are used a lot but causing maybe misunderstanding so you want everybody to have the same understanding of that and also what does not change often so this should not change on a weekly basis but I would call it a success it's maybe every few weeks somebody goes up and changes something with a pen or redoes one of the diagrams but not on a weekly basis the second value I see in documentation is to use it to surface and understand complexity on this particular wall of common understanding that we had on this team this was for a relatively small system I would say so we actually had some space to put up some more detail descriptions of some things in our code base that were not revealed but quite critical to give you more of an example this was a project where we build web application with offline first features so we have a lot of non-trivial stuff in how we stored the data so there was stuff here like the design of our storage module in the browser how how we were syncing data back and forth between the browser and the back end and also our data schema migrations and these more detailed descriptions of complex stuff all turned out to be something that you could call an infographic so this wasn't like a presentation slide or a visualization where you want somebody to look at this for half a minute and then they're like I I get it now but this was more complex stuff so something simple wouldn't have done it justice so it was like more of a mix of text and visuals and things that might prompt you to create a graphic like this would be yeah complex things that you don't touch frequently but every time you have to touch them you're kind of like how does this work again and you might say now that maybe that's the smell in your code is every time you touch something you kind of don't really understand anymore how this works but then actually trying to create a documentation like this helps you check if what you built is simple enough if it's accidental complexity or if it's just inherent complexity in what you're building and if it's if it's actually a smell and it's too complex and also then especially you should document it because you might not have time in that moment to fix it so when you have the time in two months or so then you might be grateful that you spent the time to describe it in a way that you can remember another age you can use to facilitate the explanation of these non-trivial things is what I would like to call a widget kit so in this case this was a set of paper widgets everything we needed to build up a picture to describe our data model so things like carts for each of our entities sketches of our screens and some representations of where the data was actually coming from and then when we had to we could kind of use that to build up this picture and this approach is really useful for things that have a lot of history so lots of things attached to them that are hard to put in writing that maybe kind of like in between the lines so you might feel better having a conversation about them instead of just giving somebody something to look at this is exactly how it works and also things with a larger scope where maybe it helps to have this step by step approach helps the understanding and understanding that brings me to the next value at I seen documentation which is to create empathy in this example the database technology had been quite an important strategic decision at this company even before the team I was working on joined it but it was causing a lot of problems for our particular team and it was also sometimes hard to keep more emotional factors out of the discussions for some reasons database technology discussions always seem to be really emotional I don't really know why so we needed an effective and efficient way to bring across our requirements to people and we use the step by step approach to try and create empathy for our challenges and we also had to do it more than once so having this kid prepared has also helped with that another form of empathy we can create with documentation is with each other inside our team there's really interesting blog post on meeting by Joe reading here pal who actually spoke here last year about empathy driven development and she talking about Thaksin is about building an empathy an empathetic codebase so with things like scripts that automate things maybe even the off comment so everything that provides context including Docs or it didn't happen and she says in there that working on software without guidance without documentation can be in xiety producing and I think especially as more experienced developers we often forget what that might be like and also today with the explosion of text text for more junior developers that they actually need this like a little more guidance maybe than we do another form of empathy I often see the need for is that between product people and the developers and I don't know how often my career has heard developers complain about product people not really understanding how the software works but I have not seen that much effort from the developer side to bridge that gap further and this is actually an example of a software description that helped us on a team where we needed to generate PDF documents and if you've ever had to generate a layout document for human users then you will know that there will always be so many cases where they say oh this is not pretty likewise their page break here it should be there so this logic to decide when to do a page break was actually something that costs are some of our beta users or a product owner to come by every second day or so and say oh in this case it's not nice can we change that so we had to have a lot of these conversations and we we had this poster to put up the the rules and the predicate logic in our code to have these discussions and create more empathy for the complexity of what was going on and also discuss what rules we could add and which we couldn't yeah so you might use something like this I think there's also somewhere out there there's like this huge diagram that shows when slack is sending a notification that might be another good example of this so we could use this to show complexity to others to help discuss solutions and also show them the scope the effort that we're having so that they yeah and empathize with us might be when you have a feature for example that has a lot of bugs that are caused by misunderstandings and finally describing our software should also be able to help create empathy with other technologists so if you look at another engineers work and think that's dumb why don't you just do this other thing and find out why the problem is hard but what if you can't because nobody knows anymore what the problem actually is which brings me to my next point which is to use documentation to help our future cells make better decisions and this is a blog post that Michael Nygaard the author of the popular book release it wrote in 2011 already about documenting architecture decisions and in there he says that one of the hardest things to track during the life of a project is the motivation behind certain decisions and that without understanding the rationale behind decisions we only have two choices in the future then to either blindly accept the decision or to blindly change it and we never want to be in that situation right to blindly to be blind to make it when we make decisions so to get you started with this a nice little tool that helps you maintain markdown files I have up here and uses the magog recommended structure of context decision consequences and you can then version those markdown files with your code and you can also force do this with words or with with commercial wiki's but actually my experience the medium or the tool for this is actually not so much the problem here it's quite lightweight quite easy to just write these things down it's more getting ourselves to really routinely do the super valuable thing and I think it's one of the most underused types of documentation I've seen so far but it's so valuable so why is it so hard I've been looking for maybe maybe there's a cognitive bias out there that is causing us to do this I haven't found one but if any of you have an idea please let me know but I guess it's because usually when we come to those like when we finally take those important decisions we have this closure and then we just want to get on with it right we want to implement it we don't want to we don't have patience to sit down and actually document it for the future and it also seems to be hard to kind of decide what are you writing down and what is not important enough to be written down like this and I think this is something where especially the more experienced developers or the lead developer on the team bring value because we have that experience to say oh this is actually something that will be harder to change later that will really affect our architecture and then help other people decide when to do this and look out for those moments and when you decide to document a decision please describe the problem as well as the solution so if you write down that you chose technology X because it's super scalable and supports docker that's not a list of requirements and it won't help your help of future developer decide if they want to replace that technology because they don't know why it needs to be scalable and they don't know why it needs to support docker and the structure I mentioned before of context decision consequences this context part can help you remember that you should write these things down and not just describe your solution and finally I want to talk about creative problem solving and I'm going to go in a quick detour now but we're sure to be back to the topic of documentation just as a slight warning so one of the things neuroscientists tell us about the brain is about the the two halves that are that they are responsible for generally two different types of thinking the left side being analytic and the right side synthetic so the left side is supposed to be responsible for our written and verbal skills and mostly linear and rational thinking and the right half of the brain to process images and patterns and it's also more suitable for addressing complexity and ambiguity and also seems to contain the centers of creativity and I guess a summary I just gave you about the left and right brain thinking from this book the back of the napkin by Dan Rome and in the subtitle it says that it's about solving problems with pictures and I really like the title because it has the notion that you might put those pictures on a napkin and then just throw them out because it's more about creating the picture and not having it forever and it also doesn't have to be particularly polished and Ron also says in the book that vision processing appears to take place equally on both sides of the brain so if you practice active visual thinking that might actually activate both your analytic and your creative capabilities at the same time so why am I talking about visual thinking and I talk about documentation I feel like that maybe the reluctance to record software descriptions is like oh it's going to be out of date soon anyway and it's kind of like yeah reluctance sometimes maybe prevents us from going through these very valuable exercises where we create these things and then actually have realizations and can get unstuck in our problem and solve it so if you find yourself shying away from visualizing things because you feel like oh it's just like one of those architecture diagrams that's a waste of time then maybe think again and think if this can maybe help you solve the problem that you're currently dealing with and you don't have to keep what you're drawing and it doesn't have to be perfect so these are all you might actually have desks like this in your team space right so I certainly did not keep these pieces of paper but they helped me think through a problem dan Rome also talks about using your hands for this so actually drawing things and not using a computer because first of all people like seeing other people's pictures and they become more receptive to them secondly it's actually quicker to create them and it can be like a constant trial and error process especially on a whiteboard and if you use a computer it's sometimes too easy to draw the wrong things because you're using a tool that already has shapes pre-configured and stuff like that and then a lot of so the infographics I showed before all of them actually evolved from from something that happened on a whiteboard and then we chose oh this actually worth keeping for longer so this concludes my walk through five of those purposes but before I wrap things up I couldn't do a talk about this topic without bringing up the probably most frequently asked questions with regards to documentation how do you keep it up to date and the good news is some of it you don't have to like the creative problem-solving I just talked about you just like you also have to throw things out and not get attached to things that you created there but for everything else how do you keep it up to date you probably don't we'll just keep it more or less up to date there are of course tools to generate diagrams for you for example but in my experience they they never quite work out for me so they either too detailed or they're too high level and they don't really help me think through those they don't really know what's important to me at the moment and in the end everything that is not necessary to actually keep your software running ultimately it will be out of state to some degree but having said that so a few things said that I do or that I would recommend for this is the first thing is same as with codes I just have as little as possible as always helps also make as much of it visible if possible so if all your documentation is buried in some corner of your wiki that you never go to then it will definitely wither away but if it's up on the wall for everybody to see and you walk by it on the way to the bathroom maybe or to read me that every new developer who joins your tea beam comes across then out of theta sness will be noticed much much more frequently also to groom it constantly you can try and find ways to include this in your rituals or your ceremonies depending on what those are for example maybe you have a weekly catch up with all the developers about tech stuff that happens that week and you could have maybe a recurring thing where you do refreshers on certain parts of your application that you don't touch often in that process also think about if you have good descriptions of that or if you need them and lastly try to make the creation of documentation a collaborative activity firstly because it's just one or two people do it then you only have their perspectives in it and secondly because if you do it if everybody does it and you do it together you create ownership of that documentation so it also increases the probability that all team members are aware of what you have and what needs to be updated and honestly this is actually something that I'm struggling with because I told you that I kind of like doing some of these things so sometimes I then as the lead developer on the team I step into that trap where I'm like oh yeah my team is doing the working software that's the important thing so I'm going to take care of this documentation for them but then maybe they might not even be aware of some of the stuff I've been doing and then it becomes out of date so this is one of my challenges that I still have with this how to how to get everybody else to be more enthusiastic about this so this is one step in that process so to wrap it up I talked about how to balance your level of documentation you should start by thinking about why you do each of those pieces what purpose it serves that will hopefully help you create some that you dismissed before like those decision records but that are really valuable and avoid those that are waste so I talked about creating common understanding surfacing complexity creating empathy help our future selves make more informed decisions and creative problem-solving so finally this is how I think about documentation when I look at what's there and what's needed so firstly there's the code and that's the only two and that's the most up to date description you'll ever have and then you have maybe maps that help you navigate the structure of your code you have how to to provide guidance and reduce that anxiety I talked about and you have stuff about your history and context so decision records are also your git commit history and you have that creative thinking space where maybe you know rubba ducking or drawing some stuff out helps you solve a problem and how much and what you need in each of those areas depends on your context right what's the seniority of the people on your team how frequently does your team composition change what's the type of application what domain is it and which phase of the project are you in are you at the very beginning or somewhere at a later stage but ultimately all of these things together should really have the goal to enable another person to understand everything without talking to the team so if you have so much documentation that your team is under the illusion that they don't have to talk to each other anymore then you definitely have too much and it's actually counterproductive so the team members are the guides of the code and the system will use all these things as tool to remember and to more efficiently communicate and the process of creating and grooming documentation in the appropriate form and dosage can actually be a great catalyst for lots of other agile principles as well so yes even at our development you should create documentation and I hope I could give you a few ideas of how [Applause] you