Style Documentation for the Resource-Limited

thank you for et and things but blue that it suffered a seventies Dell application for the resource-limited mining is that the people and 2 days you we're going to be talking about ways to get style guides done in the real world as opposed to the happy fairy world where you actually have 3 months to take to stop reminded us and so whenever you're getting things done under resource constraints it making a style guide for anything else you to follow some basic steps 1st off you need to have a thing here in for you don't have vision where where you want to go you going to track back and forth and you're going to kind of sit along 2nd we need to figure out baby steps that you there and then you need to scale these baby steps a bit further down you're always going to really overestimated and how much you can get done in any given the step at 1st and so be realistic take a few times go no really I'm going to have 20 minutes of data into that's what they do and 1 minutes you're also going have changing circumstances to adapt to to taking 20 minutes data do this then you're going the coding and your teammates are going the coding for a lot more than 20 minutes of those days you need to hit from a moving target so nothing is going to really be quite let you expect at the ends of the vision that you have at 1st is great it keeps you motivated and it keeps you focused but resign yourself the fact that that's not what you're going to get what what you're going to get is something that's actually kind of cooler many data effect so this is a additional what we have here is the 18 Apr style guide 18 F is a division of the US government I like this is an example style guide because the kidnappers a collection of small teams that consults for the government agencies I could use other examples like Google's material design here but since material design is built for Google scale companies and since most of us cannot work at Google skill companies something like this that's a little tiny areas a bit non more realistic but also or more adapted to or specifically it's not Google's needs the we talk a

lot about getting everyone on the same page where business logic is concerned we talk about developing a shared ubiquitous language that you can share with stakeholders but the thing is we use separate shared ubiquitous language for a user interface logic we when you're doing what development we distribute this user interface logic through the H mount CSS and JavaScript and heating is organized is not actually an easy task because it's so distributed this coherent model that are going to build is what lets us to do that and not go insane that is that's able which inside come and things you already have Nextel your axonal style guide is your base all other forms of look basically like each other I think probably and this is achieved via liberal use of copy and paste this is great if you got a small team or a small UI or anything like that but as you skill not it gets a little trickier to deal you start onboarding you're developers arms and they don't know what to copy and paste from they don't know what the right parts of the axonal style died why rails gives you a lot of really useful to I'm structures for organizing your business logic not as many as some people would like but I'm not if you open up and you realize that you know where the controllers at going being in you know roughly what they're going to do the same is not really true if you code every shop has its own funky little way of doing it and that's not transparent also realistically stakeholders were not you especially designers are going to have a lot more opinions about the results of the view code than they are about the results of business logic they can see it's easier to talk about an easier think about tha so there's an example happened when returning to a few different times in this talk but I'm not gonna coherent model of user interface I want again stress this is about looking at repeated user interface concepts not just these are not in the context of the user interface domain cattle modules the cards showcases the reason I'm making this distinction is because a designer might want to reuse the same concept to slide off us or they might want to reuse or inter probably going to also be slain cat photos another way and if you're making a catheter sharing website style guides to

also go a little deeper than your branding guidelines a lot of people go OK we use Helvetica and stop there by a so they can do a lot more you can pop up a look and feel of individual which this tends to be as much or more about the affordances as components as is about the esthetics you cannot about how the range of labels next the form fields on top of them word error messages that we can also talk about what you i problems are given which is useful for solving you can say use carousels if you have need to display several bits of cards but otherwise it's just use the or you can say only display notifications if their relevant to the user's current and this final basically good

step application it on so you might be thinking this is overkill we just use bootstrap just is a really funny word in Suffolk felt it is usually a marker for someone trying to push their assumptions on you without realizing it and the thing is that none of the people of ever pushed back and said that to me work actually just using bootstrap if you think a shot just uses bootstrap I'd like to ask yourself the following questions are using all of its rapid just a subset are you only ever using bootstrap or do you have custom UI elements that are part you have undocumented bits and pieces of code or rules around how using the bootstrap elements and again and most importantly too often copy and paste market mark up around preserve these undocumented rules that's the most useful real world heuristic I think at the end and so if any of these statements are true about your site a style that is not the same as the bootstrap documentation I'd like to encourage you to document ways which is different and you don't necessarily need to be super fancy about this it can be annotations with wings that say more direct more docs this link this link happens been bootstrap box but still documenting these deviations is very important that's the other barriers style guide adoption on just look like we need this they are excellent work they are it's a lot of work and my boss will not let me do this because it's a lot of work there's also a few fuzzier ones if you build a style guide very inflexibly it's not going to accommodate a real world use a and this very well similarly you might have a designer who believes in a lot of exceptions to the rules rather than just a few arm and finally if you make a style guide once and then assume that sentence down it's going be just another senator documentation it's going to slowly drift away from reality we live in the real world or soccer is held together by love and duct tape and I say we for a reason probably most of you I'm a veteran of the we can always make it better at some iron school of agile and because of that I can tell you that actually you can use incremental the you can get this bright shiny dream world in the real world the 1st thing we need to do is let go of the idea of the style guide is ever going to be done it's in 15 years as the Agile manifest we have all embraced a notion that our software Italy built and never quite finished it follows that our documentation like could mirrors needs to be responsive to changing needs needs the malleable as part of the sound and before that was this pretty thing that the designers but a room and built of course a few months it was great for about 5 months after they finished but then the lead designer lechmere place and it is I went into another room for another 2 months yourself and built as a new style and it was beautiful to but we're suddenly face that this dilemma Due we stopped rolling migrate to the 1st 2 we leave our user interface inconsistent states what we know and none of these options were great for users and a lot of them involve busses taking time not shipped out so when we do these things as perfect versus worthless when we hold up this perfect ideal in our head and we expect that it's actually even all that useful in the real world we suddenly stopping here processes because we think there's no point this sitting industry has proven time and time again in the area of processes work much better then stop the role processes or having for fan never doing anything at all who here is written brownfields testsuites before so take another uncovered a undercover codebase and reducing tests and that's a lot your hands and I expect you all really lucky or something because when you use this kind of sucks you tend to pick 1 you AI Capone right integration test for it or you pick 1 method in 1 class and you start writing a test for all cases and it's really really terrible you do it for features you working on you at the time that by it still really really terrible if I maintain some kind of lost in your feature and you don't have any kind of proper test harness you're needing to build that simultaneously into kind of fake it go and good enough maybe in the response but the next steps after that and still not honor anything but it's such a lot less you already have a minimum viable test time is in place and so you can just write your test or you can maybe even flesh out your test alone and make it a little more full-featured and eventually gets easier and easier and easier and then it gets easy and that is the greatest feeling and I'd like you to think to think that brownfield style guide documentation in the exact same way because it's the same thing the great news about looking at Brownsville sound I documentation like Cranfield testing as inner it as an iterative process is that lets us sidestep many of the real world concerns I outline for you outside it also forces us to figure out a set of baby steps that lets us maintain velocity well we build our style guide forces us to make things a little bit better with every little baby steps so that we can prove to our teammates our bosses but this actually is worth doing and forces us right away to grapple with the dead documentation problem is something stop robot project released on April 27 2014 I know coming in the project that it was relevant that I can adjust my mental model of how accurate is based on like some mental heuristics around code it so underneath that project circle of May 2016 I can know that probably many of the database tables are about the same they might have a few more columns but the general structure still there they can throw out anything the documentation says that the controllers as completely irrelevant however if I have bits and bobs of documentation that don't have dates on them I don't really have any way of knowing how useful any given case that it's so the 2nd it starts to drift wave melody and I notice it's inaccurate I ICPs seem can make the same value preserving code entropy tight work because I don't know when it was accurate so I just kind of need to dismiss the entire thing so that we need to solve the debt documentation problem really that very much 1st the but also lets us sidestep be that's only problem we document we've already got to leave the rest of it away and leave any kind of organization for later we know a style guide covers real-world use cases yea so might teach you a three-step process for getting a style guide up currently were going to use a 3 steps over and over and over again in which we identify UI component could it and then document step 1 identifying is we just look at our ap when you look at the screen side by side they both got pictures apart where they both got hard on them and they've also got concepts so we packed concepts 1st when we get to VII of step we formalize these components code when we do this we try to re fact we've already got 3 more internally consistent this set us up document later and it also helps us sell this process 1st directly we can always say this new process changes in application is going the magic and solve our problems because we don't have I teammates cannot be expected at that point had context for why this is magic and why this will solve the problems but it is very easy to say hi I'm proof these 5 lines of code and get people say yeah on so this is going to be something used help build trust as well as set ourselves up for success fragmentation so the heads up we're hitting the code on slides part of this talk is last status after lunch I'm really sorry I'm pleased focus on a broad outlines most of the slides have helpful bright red circles on them to point you to the interesting parts at the end of the talk and winking giving you a link to a blog posts and link have all the samples and answers so you can look up every bit of code on the slides later the 1

reference please again think of this as a general overview it happens to include the courses like has a helpful red lines on it but also I mostly just doing this up just show you a on refactoring code that's kind of repetitive and I'm going to spin pasta and overlay these 2 things and patch unaffected code is really repetitive sometimes this is an overlay of those 2 things note that you can't really tell because it just looks like text but and because the rails project we're going to use a helper to refactor us know that I'm putting the output HTML in a comment directly above method this makes reading the method quickly much easier it is a literal representation which can be a lot easier to read than content and it's a lot easier for a designer to read than content and because you designer knows each to military lucky that is not going to probably and and also helps you search for could more easily in large projects which is a lifesaver and so we move attempted to use that help where it's nice and pretty yea look how nice look shorts this is what you could be section looks like right now that's OK fight years ago front and that he was that of sound and probably would not said this is OK but I was wrong and market frameworks include step and Foundation which are what's going usually give you like use a huge sets of classes are really useful rapid prototyping tools and in the real world it's fine that you don't always have a chance to go back and make protect this I also 5 years or financed not Betsy when she said you presentational markup was actually missing the thing that's really wrong with us we look at these 2 examples from the semantic versus presentational nerd fight obscures the actual difference between the 1st 1 at the top is us using the mark up to list out a collection that it's that you can't have on the 2nd is OS convincing that said it actually it's into a useful distraction that builds out the shared this language of user interface and so how do we get from 1 do quickly we treat and this she and family is great even if you're not necessarily as control of CSS if using rails you probably already have a CSS installed and that's a market preprocessor that gives us a few different options like Nixon's placeholders in class extends that we can use to include existing CSS classes into new ones much like pretty modules so all we really need to do here at least on a 1st pass is made apparent last that encapsulates the and then displaying all the CSS might be become classes into that using class extension this is not the world's pretty assess CSS but again it's better than what we had before and in a lot of ways that's all that counts generally this particular approach is pretty safe the fact that we're making you can class helps us limit the area of affective factors but sometimes abstraction requires a few nested that's you can't clap some quite this easily on and he may be can fix 7 how you have or maybe you do try this approach and something weird happens with the cascade the CSS is very global oriented language and then you go now and back up and that case the next most heavyweight mitigation technique I have radio is building a nested helper this is starting to get in the end of code that's clever for clever state so the market is simple it might not be practical abstraction is really only useful when the thing you're abstracting is complex so yeah cited open nesting looks like DSL magically outside that's the simplest possible form of on match but we do is we build the outer tag and then say this insight is going to the content of a block that's passed the medial control that are bloody that something even more complex when we look at the screen these above both cards that the really different kinds of cards and saying alot of configuration options my as much junga developer the way would do this would be like the mega helper approach and I'd be really proud of myself because I was making fewer lines of code by it would be a really bad abstraction and I would not be able to read a 4 months later helper nesting can help us but when I look at this particular instance nesting I wonder how to make it clear that the body methods are really only ever intended for use within the parent I can help the people of this cone get at but if they guess wrong then the errors might not give useful feedback on the other hand when I'm trying to solve this problem for my co-workers I need to make sure I'm not building some huge it non z things because no 1 wants to learn the hipster Betsy framework that's not documented that's what I do is I take form for is inspiration and former builders I'm not strings rails weight here I'm leveraging its metaphors so that you can use them to understand this code and this is great it helps me Celeste coach my teammates if it doesn't become doesn't solve people's escape code does not improve my teammates lights immediately I'm not going to get by and for that code and nor should only change pattern using all that much for so using the builder thing Emmanuel Control Act is just that instead of yielding to 1 or instead of building 1 parent had 4 billion object knows how to render the entire components know the passing in the new context this is the class all helpers and fitted into when you build a real scale we remedies in self and injected them on and on there 2 different schools of thought about highest supposed to inject contexts into non helper things that use use and I like this method it's least magic of them little verbose but no magic and that's the basic component builder is going to have 3 major parts initialization a rendering shall and a collection of sub and there's the only thing you need to do in the initialization step is gravity context and 2nd act using H that here which is convention borrowed from draper I usually hate single variable names but this year the Convention lets us focus on all the time the call content tagger link to or the actual methods if a just taking the context over and over it obscures what's important the other thing you can do if you need to initialization step is configured top-level CSF factor-beta repeated Texas stuff like that In generally 1 of the this configuration pretty light weight we want to push the bulk of the work to a subband there's so next we build a render of this looks remarkably like the parent of a nested helper out it's the exact same thing an arm and so again we're just building up the order tagging and then work yielding controlled the block the sub injuries are going to give all the work they going out of all of the different bits that form the main the main body of the UN and know that again here were still adding comments that eliminate what the market generated is we can anchor ourselves I personally find code that's very content had heavy hard to read on and this is a great way of removing that layer of abstraction temporarily so I can focus on what's going on rather than what this code is doing again got this all mold up the way to implement this review looks a bit like this when you're testing these these reasonably Gary or picture axonal parser I don't care what your in the country at 1st to try to test them using plain strings or maybe the tracks that matches against those planes strings and that's when he really really brittle it will seem simpler 1st it will not be simpler in 2 months learn from my mistakes and again all of these techniques have shown you are in many cases pretty heavyweight you don't always need to find a male for any given you if you got tells you these techniques are overkill your project trusted when she finished codifying the pattern the next and final step is document and this

is super easy because it may be is cut comments and they start the documentation for us for bonus points where you can do is you can use our docs include director to link to any given partial orders that you might be using within your code and

those actually in line in R . by magic which is a really great way of making your documentation up and on upgrading documentation is super important because then you do not need to actively maintain it and it can stay reliable without further input from you but only a developer server going to look your artifact probably we want communication tool that lets us communicate with designers and maybe other stakeholders we want something like this luckily is much less hard to build than you might think looking at this like nice finish looking thing since this is style documentation for the resource-constrained rather than style documentation happiness point fairyland need to ruthlessly prioritize but we're going to include on the 1st pass the great is is that that not that's not that much there are 2 real-world use cases that this document is actually going used for we just need to make something that encompasses both of them the they are a developer skins are developers given wireframe and skims through the south side from fossil looking element which they then copy and paste into their time working code the other is Lusignan belabor talking and they point to things and so given these use cases are minimum viable product just these pictures of components and example code for those components anything else on top of that lake use-case descriptions etc. is great especially if you've got a larger team but you don't need to do that in the 1st pass and I advise you to not do that in the 1st pass and burn yourself that they're given the tools they can use to do this my favorite tool for doing it in Ruby is a tool called hollow-gram it's a jam just install like normal and some of the best I a tool for you if you're using JavaScript heavy fun and and light angular Amber reacts whatever I think that's the this is using and is when the tool called KSS column you want a new version of the Xs and you want this for 2 reasons and 1 of them is that the node version of the SS is actually the only version of KSs that has a lot of the features and when talking about is important later the other is that your style guide generator language always wants to match of the implementation language so I'm going to be using hollow-gram in all of my code examples as Israel's it works I read a little like God you put special documentation comments from your CSS files and the processor transmits documentation pretty adopts near CSS or someplace else central is a great little money spiritually it's a keeps documentation times it's really easy to forget the prioritize documentation when you keep in doc random stuff but market it's harder when it's right above the code you're working on yelling I'm here fixi you're going to feel really guilty if you don't a Sundance out generators also going to give special status your code examples like condition you here programs output looks a little like this in a super happy little picture of a card right about the code makes the cargo for fulfilling both of the needs of a style guide and the the right in 1 tool it gives us this both of these by not magic but writing because stops here but we can also get a little better the we

don't all the schools you helpers that could fire abstractions and the hologram processes are just executing Ruby just like KSS no prosecute processes are just executing and so we can put our help person these examples the sticks little bit more more work to set up it's a little finicky it'll rails version and and it's too much could be worth putting on a slide but it's going blog posts money showing you later if you knew this I advise you to super magic because then your markup changes and when you update your helpers all of these changes automatically propagate your style guide and so again you don't need to do as much maintenance work going on living style guides are way more important and work our way more useful than 97 forget so the ideal something that looks a little bit like this note that the example without which the HTML helpers generate and helpers themselves this is really important for helping designers it lesson prototype rapidly using your actual style that from and they can do this even if they're not necessarily that comfortable code because that's right there for them to copy and I'm going to describe something for you that you think will never happen but it is happening all the time and that is the designer actually does make 1 of these prototypes and then the designer comes to me and gives me this prototype go hands meanwhile the separate agreement was released million ghostly wonderfully I notice something that's not quite right like there's a little bit of content that works differently in the real world but it didn't designers happy lorem ipsum I'm going to make things up world and so then what we can do because we have a shared understanding because we have a shared code we have built out document is we compare on how to make things better we don't need to we get to lose about process where a designer and developer started yelling at each other and your were giving past aggressive once every 3 days comments in Jira about impracticality in ugliness because we can just go and talk to each other and we've got this mediating document that helps with that it lets us workmen's really fast happy user-oriented where I am at former fun if you're doing that if you have a style guide that led to collaborate really effectively and happily and it then it doesn't matter if is a messy and changing working documents honestly I think that kind of helps it means that if it's accessible and it means that when we need to update it and then making those updates is accessible rather than something we need to treat as a big deal so to take 1 and only 1 thing must talk it's that that is the goal and it's so you can achieve the 1 quarter is an eventual is if it works retrieval it's important understand the building blocks of you I it's important to use abstraction effectively manage those building blocks it's important to constantly communicate about what this building blocks are to keep an eye on the same page whichever method you use you can never string you deserve to get to the stream the blood feud so here's a link to both the blood because of could samples in a blog post from pivotal it helps you set hollow-gram up with rails in some nice ways that keeps Godard that has gotten to order the things on this is me on my that see I'm on the unit of the places my Twitter is mostly feminism and pictures of my at an occasion science fiction and occasionally also close to on I work for an organization called act blue we build fund-raising tax for Democrats and we amplify the voices of small cellar donors I'm on average duration size is about 3 dollars and since 2004 when your founded we of raised 1 . 1 billion I'm about 0 . 1 billion of that has been in the last 1 month 2 months alone like about that OK the and this helps is donors voices be heard in a real way by aggregating it's what really helps us keep the party more focused on the needs of people don't have the sensor domain means a lot to me were committed to a modern web development stack and a culture and technically sustainable approach I and we're hiring please talk to me here to my boss is going raise hand if your interest and have I'd like to thank growing area and K. S. Hoffman the people of Arlington Ruby and zeal and act for all giving the feedback on earlier versions of this talk in helping me make it hopefully good any questions yes absolutely

and when heat weeding out this but we do not want to right after I set off the stage yeah it was a we are located in Massachusetts but we're very remote friendly I live and you see we probably have more developers and I'm at this point and it's a great remote culture I can't say that from experience tha good thank you for coming and I my my ball