GitHub GitHub Universe 2019 - Skills, 17 Dec 2019

Previous Meeting

Next Meeting

⏯

youtube image

►

From YouTube: Changing work culture through documentation - GitHub Universe 2019

Description

Presented by Tania Allard, Developer Advocate at Microsoft

Most developers have heard “good code documents itself” or “documentation outdates easily, the code does not” at some point. This is an excuse to not write documentation or justify the absence of it. In my work with many teams, the lack of documentation is often a symptom of high technical debt.

What if we could turn this around and use documentation like a driver for positive culture change and start paying the critical technical debt? This approach not only helps teams to faster identify areas that need critical support but also brings more empathy to the table.

In this talk, Tania draws on experiences using documentation as a weapon for positive culture and process change in machine learning and scientific computing environments. She focuses on the processes and approaches that enable the creation of documentation for data scientists, infrastructure, and software engineering teams, and clients.

By the end of the talk, you'll learn efficient techniques to make documentation a first-class citizen in your development cycles—and leave with one or two tricks to convince even the most reluctant developer to document code.

About GitHub Universe:
GitHub Universe is a two-day conference dedicated to the creativity and curiosity of the largest software community in the world. Sessions cover topics from team culture to open source software across industries and technologies.

For more information on GitHub Universe, check the website:
https://githubuniverse.com

A

Hello, everyone and thank you for coming to my presentation. I am Tony Olerud and I'm. A developer advocate for Microsoft and I'm, based in the UK I'm gonna, be talking about good code documents itself and other lines and justice about how we can start changing our organizational culture through documentation and how we can also use dogs to pay some of our technical debt. All of these lights are CCI, so feel free to use, remix and adapt.

A

As you see fit, and here is a link worried you'll be able to access all the slides after ADA presentation. Oh so, just a little bit about me. I am in open source advocate and I worry Microsoft with all of the open source communities that are science, communities and researchers. I also love complex systems. I have a background in research in this and as such, I specialized in all things, scientific computing and machine learning, and that aside, I also love mechanical keywords.

A

I like using them, I, love, assembling them and I often share pictures of this on Twitter.

A

So what you're going to take away after a test presentation? First, an understanding of what is technical depth and how is that? You probably acquired some of this in in your projects or your organization, we're also focusing on documentation as an entry point to identify and pay this technical depth and also some useful trade. The tip sorry for you to use documentation to drive change within your organization, no matter how big their team is so I'm, just gonna ask for a little show of hands of who likes writing documentation.

A

I love writing ducks now, who actually writes the cumin tation as a regular practice, let's say day to day under normal water flow, each sometimes cool, and what, if I told you that you can actually change your culture? Your team's culture is through writing more ducks or writing better ducks and also be some technical depth. I know this sounds a bit like a dream and like a wishful thinking, kind of thing, but it's not.

A

Let's start by identifying what is technical depth when I think about this I usually think about the monster that leaves under my bed, my bed or inside I close it, and we kind of want to believe it's, not dairy but we'd, rather not look under the bed or open to close it in case it is actually a real thing and but it's very very insidious. It starts creeping off little by little until it becomes a very, very big thing out of control.

A

So basically, technical depth starts with a series of bad decisions that are eventually leading to our prone code or architecture, and such decisions can also lead to unnecessary years or bad years of certain resources, and these resources can be either infrastructural or people or other sort of resources.

A

So whenever you start thinking about technical depth, injury infrastructure or injury team, it's always worth to think what were these decisions made in the past that prevent me from getting stuff done today and first of all, eight days we have told centers and what causes technical depth. In brief, you and me I would like to talk to any of you that have never contributed to any technical depth and some examples in which we'd rmally do this or in which I have been gullible.

A

Of doing this is by favoring nice shiny feature is instead of favoring tests or robustness in my infrastructure, something else that massively leads and contributes to technical depth, ace time crunch when a project or a new feature or any release, was to yesterday or is due today and it's four o'clock in the evening and when we start doing working on this time crunch on this very short or tight or unrealistic deadlines.

A

We start doing things like I'm gonna, write this code and then I'll come back and tidy up later a week or a month later, and that doesn't happen or I'm gonna come back and write the documentation later and that dots never gets reading.

A

This is something that also happens a lot in because I work a lot with machine learning, I'm gonna use a machine learning example. Now deep learning is very popular. Everybody wants to do AI and some people want here's the latest trends or the latest algorithm, because all the cool faults are doing it. Sometimes you can use a more a much, simpler approach to get similar accuracy or similar predictions, but we didn't do it or it some folks, don't do it.

A

That's also an example of technical depth and we're favoring, blackbox algorithms, or a very, very complex infrastructure to tackle smaller problems.

A

Also, being a NAND already broken Cola tree and when you're already working in an environment where everything seems to be a pile of garbage, it's very very easy to think. If I add a ton of it to that pile of garbage nobody's gonna notice. Am I right yeah?

A

So how can we start identifying technical taps? What are those can create little things that we'll see in our code bases or in our worry that will point into technical depth a lot already discuss today. The different decisions are two different social parts, but Frank said we one thing that Clairol indicates this code smells that are not necessarily bugs, but our indicator is of deeper problems.

A

So if you go to your codebase and find a half-baked feature, Eden was rated probably six months ago and nobody had time to go back and revisit and make it more robust or die or tighten the implementation. That's a code smell if, despite of your code being on git or github for that matter, is you started seeing a lot of commented out pieces of code? That's also a code smell and it also reflects with well I'm. Writing this piece of code and that or this function that will replace this other function.

A

But what if I later I need this previous part, but that never gets deleted?

A

Also, would you go to your codebase and don't find tests or even worse, when you find tests that are broken and have been broken for a very very long time? That's also a significant code smell multiple versions of your CI order, city descriptions, but only one in years, I've seen DS quite a bit where folks are using a certain CI or city provider and they updated.

A

But then the old one gets moved to another directory inside the same repository where it's old, CI or something of the such again, just in case they need to go pack or flip back and no documentation and poor documentation is also a very big indicator of these technical depth. Smells.

A

When we talk about infrastructure e and something that it can also lead to this, a or e indicate high technical depth is having this house of cards infrastructure where, if you move a tiny component of your infrastructure or your code base, all of the things that are rounded will just suddenly start to crumble. How many of you have ever been in a situation? Murari you've wanted to modify something, but somebody injury to you tell the oh, no, don't touch that part. It just works like that.

A

It doesn't need for factory, don't touch it not even with its take, didn't look at it just at all. Yes, I've been there, so that's also an enforcement. A bad one, and another indicator is that everything is on fire all the time, and sometimes we will have monitoring is good.

A

Having monitoring and and having am sorry tools in place, identify when something's fell in our system is good, but when we're getting alarms all the time that everything is on fire all the time, it's a very easy to lose sight of what it's really important and what is there really critical porridge a night there? Our code base or our infrastructure or our products, and then it just seems that eventually, because everything is ever all the time on fire, you are a living in two dumpster in fiery.

A

So not only everything around you is failing, but your team is constantly anxious like that. Little foal, kinder.

A

Also for those of you that work more in a more data intensive scenario, having unstable or underutilized data dependencies is terrible for those of you of what well. There are not very familiar with machine learning. For example, when we're trying to do predictions, we tend to aggregate data from different sources, so that can be different. Api is the friend databases, but for us to be able to utilize this data and we need to do some transformation and some loading and made it make it accessible for other folks to use.

A

So if down the pipeline, you end up with 30 databases and you're only only needing one, then that means that you're having 29 databases that you still have to maintain that you still have to provision infrastructure that you still need to compute on to get to those or you only need one. So that's also very, very bad and pipeline jungles.

A

This is very related to the previous one worried all of these dependencies or data dependencies become intermingled, so it becomes very hard to understand the word data is coming from and where it's going to so you can't really understand how their data is being utilized or how to improve the performance of this data transfer.

A

So now that we've covered all of these spreads of technical depth, which is easier to do when we are dealing with this phenomenon, either burning everything to the ground, refactoring or a code base or a changer world-weary culture is to use sub pointing fingers. This is number one number two for those that love refactoring and number three. No, it says easier now, which is more impactful today, one two, three three, it's of course than the hardest one. It's the one!

A

That's gonna take more of my aim from the different stakeholders more time and probably a lot of fights so I'm gonna start doing it the story time, because we all love stories and well George, github universe. You are going down the sponsored boots as we always do.

A

We're gathering swag like getting Jace near t-shirts and pins and exchanging pins with faults, and you come up to this new birth that is labeled as The Wizard of Oz, like oh, okay, I've, never seen this fault, so you approach the birth and the with story tells you he's gonna, give you a present. Oh I, like persons, I, love swag, so.

A

This person comes with a set of rules or a with a set of conditions.

A

The first of this is that you have to build your present. You have to put all the pieces together like okay, I am cool with that. I have built mechanical keyboards and I write code for a living, so I'm cool with that with no instructions like well, there is stuck overflow. I can do some internet searching. That's fine I! Do that all the time? That's how I got a job.

A

There are more conscious even some pieces are my be missing so as you're building your present you'll have to build these pieces as well again with no or minimal instructions, so because you're making this on the girl with no instructions, some pieces might never fit so you'll have to use glue and tape and probably chewing gum to put them together, which means that your present might or it might never work as expected and a wizard worst part.

A

You're gonna be miserable all the time, and this picture is a very nice representation, they're, probably trying to put that piece of mirror on the ceiling and paste it with a piece of chewing gum, so the next time that you're walking near it it might or might not fall on your head.

A

So when, when you receive a present with all of these different God chests, you realize that that's not a person, that's some sort of a curse, and what do you tell the Wizard of Oz go away? Wizard I! Don't want your curse. I, don't want your present, so this is now replace the word Wizard of Oz by your monetary or a senior colleague or during onboarding body.

A

The present is the code or the code base that you are inheriting at your company and all of these little gotchas missing pieces is all the technical depth and the lack of instructions is the lack of documentation that we are facing when we are importing a new project.

A

How can we counteract all of these frustration? One way to do it is writing the docs and the other way to do it is make Doc's valuable for the developers for your team for your customers.

A

Dogs can be part of your work, and you know the in teams were people were not writing dogs a a way to forest folks? To start writing, dogs is making a part of the job, so no feature is complete or no new code base is complete if there are no equivalent comments or a documentation to go with it. If you force this through using jury, CI and testing your dogs and building your ducts through your continuous integration or your continuous delivery pipe lines during forcing these practices.

A

There is a bit of a trade-off here because it does worry from the technical perspective, but also when you are trying to get Gerry team tie in you will probably find a lot of resistance because nobody likes writing dogs, so I'm going to give some tips later and how you can probably incentivize folks to write them.

A

One of these is also when you are trying to write dogs, especially for a library that you maintain or for a new feature that are implementing.

A

We don't like it, because it feels like we have to do it, but if that's something that we have to do it, a good technique is thing that your best friend is going to read. How do you want your best friend to be introduced to this new feature or to this new library? Be mindful? How easy do you want it to be for them to enjoy Diaz and start using what you're evolving an example that is very well pristine. The area where I work is a supply.

A

A lot of folks praise how completed documentation is how good it is for awarding new contributors as well as new users and a technique that I really like from them, is whenever they find anything that is confusing or whenever a new contributor or a member identify something that is come few thing to get the newcomers to contribute back, because they have less of that expert buyers than the core team normally has, and by doing that, the team has also been able to identify some critical bugs and fixes for this box, because once you understand and you're so deep into the codebase, it's very very hard to get rid of that expert bias.

A

Something that is very important as well is thinking about the vocabulary and how we are writing this documentation for many many years, us as developers or developers, have used terms like mastery and slave, but this can be extremely complex in terms of power structures and inclusiveness towards our a multicultural users and multicultural teams. So, whenever possible, try to replace this terms for others that are more mindful and more inclusive. For example, a good alternative to mastering slave is using primary or replica quick captain and sailor worker and helper the same.

A

When we talk about blacklist and whitelist, we can replace that with terms like deny list or allow lists and, as you start using much more inclusive language on your documentation and be more mindful of both the people that are, writing it and are reading it. You can also start having dis conversations with your team, and your routine will become much more mindful of those that are integrating your use-values ways.

A

If you don't want to manually, go and check all your dogs and all of your white papers for this incidence, there are different libraries in one library that will help you a lot to do. This is called Daleks.

A

It's designed to catch these occurrences, for example, and incidents of Master and slave, and they give you alternatives for you to use. There are more gender neutral that are more inclusive, and you can use this from your common line. You can use this online, they have different limitations if he is an even Visual Studio code. There is an extension for that.

A

Also, we were writing documentation. We have two levels like two different strands of documentation. First is the comments or in code documentation versus the public-facing or the user-facing and curious. Where a lot of folks say well good code documents itself, you don't need to write big documentation. You don't need to write comments because documentation out dates easily and code. Doesn't some other folks say well if I don't write a documentation, I'm the only one who knows how this work so they're, never gonna, replace me, but the thing is code.

A

Tells you how you're doing that how'd you achieve a certain thing if you're writing a function that retrieves data from a database and four months in a permit set in an appropriate usable way. The code tells you how you're doing it, but the comments inside re actually tells you why it gives a much bigger clarity and your process of thought. As you were, writing said function or it said method, and they describe direct code to other developers to whoever is gonna.

A

Take care of that code base later, whether that is your new on board member or your best friend or yourself in six months time.

A

Documentation, on the other hand, describes dysfunction or a dis methods, functionality to your users and as a guideline when I tried to write documentation and help folks to improve your documentation, I liked recommending tests that I called mindful structure again. Its main goal is to get folks up to speed as fast as possible. You want to get your users to lower data of deputation or ingestion barrier and start using your product as fast as possible.

A

So if you first start by explaining featuring what is that, it dose then describe some use cases how people might be able to use it, and when is this function or this method better it another alternative, if there is any additional recommended tooling or any additional recommended importance, and also common error is very common gotcha. This is something that is often missing documentation, or sometimes we update databases. It's sorry code bases.

A

We forget to add these little gotchas on this is imported now or a DS replaces odd.

A

So, if we're writing to your documentation, do realize that you're struggling a lot here. Is this mindful structure you may also need. You might also find that you need to refactor it at specific piece of code, because if it's not clear, how do would you set when you would use it and when you wouldn't, you said, probably you need to improve that.

A

And I've mentioned a lot of times already that your documentation, healthier user, is to avoid Ori to use your feature or your library or your package, but documentation is also helped. Your user is to make the right choice and you want this to be also Smith. Do you want them to use your product because it adds value to whatever they're doing, not because they didn't know better, but it's also a very good way to build trust between you as a developer and whoever is using jury tool or is contributing back to your tool.

A

And I'll also give them useful starting points, something that I've that I, like a lot is when you can start seeing how other people are using that tool straightaway and find a code or a workflow that will be parallel to your is also when you're writing your dogs, trying to make the abstract tangible. Sometimes we like describing very complex, architectures or very complex functions, but we could do the same or achieve even more if we added schematics that are easier to read.

A

There are a lot of folks, especially like me, that are very visual. So if you were to give me a schematic like this, that explains how three different packages or libraries interact together. I would understand it much more and much better and much faster than having described in words and also trying to introduce the people again who's going to be using jury tools. How do you think they're going to be using them?

A

Sometimes we can't anticipate who is going to be using my other tools, but if you have a persona- and you say well, for example, this developer Jane is trying to achieve that. You can also drive how your dogs are being written to help avoid someone like Jane.

A

And also think about design patterns, if you have a chance later on in is Montana gave a very, very good keynote at PyCon India.

A

She one of the founders of Spacey, that is, a library for natural language processing and a really liked approach that they use worried their library tries to give them the power to do NLP but at the same time use the nicest features or deny cities of so that way, not only dari using interlibrary, but they're utilizing pythoness language without them having to spend a lot of time supporting little features that would marginally make the developers work faster, but will constrain them a lot.

A

So also think of that and in having documentation about the limitations and how's your tool integrates with other framework, can be very, very, very useful.

A

Again under under adolfs manual Docs, we for it for many areas with not had to write our documentation manually or separately from our code. If you're already adding comments or if you're, already adding an explanation with the injury code waves, there are a lot of libraries that allow you to generate literate programming or literally Lear literate. Sorry focused documentation, something that I used. A lot is Piko, that is the implementation of dokgo, because it gives you these very, very nice views of documentation.

A

Were you have the comments in your code base and then when to render d-dogs you see all the different dogs side by side were in the code base that originates from.

A

So this should become easier and more natural, because, again, if users start enforcing this as being part of their job being part of your pipelines, you don't have to do extra manual level. It's already integrated as one of the automated checks or one of the checks that you run along with testing and building and deploying so non-wage, ensure that soon, as you create a new release, the equivalent documentation for that Nene release is also up to date, and it's also maintained.

A

You know something that I've worked on a lot and with great success is having dr. Sprint's, and this helps a lot with that notion of you're, forcing all of a sudden injury team to write Doc's. We organize a lot of code sprints or we organize hackathons. Why not organize saying dogs sprint?

A

Nobody likes doing it, but if you sit people together and it had all regular timings and probably bring tail traits like I, don't know done it's or fruit. Sorry, hello, my fries, whatever your team likes, then they feel like they are all on the same board. Did they help each other, but also let them choose give them the freedom to choose on what documentation they want to start working on. In most cases, people are gonna start working on documentation for features that they implemented themselves, but never had time to go back and document.

A

If enjoy team. You have both native and non-native English speakers or German speakers or French speaker is what average or documentation language is paired them together.

A

So make it a joy of writing, Docs and I. Really like this. This suite from a book that we were running were. We were never expecting someone to come and say: I really really enjoyed writing a chapter on linting on linting right, um but when you said the right, the right mind frame and the right environment, people can actually start enjoying writing dogs I'm just as important as it is to recognize those who country to Georgia commit to your code.

A

It's important to recommend and recognize those that are a contributing to your Ducks and that can be writing and tearing your pieces of documentation, fixing typos and making it more accessible again. Make it easy making it easier for those newcomers to embarked.

A

So why ducks? Why do I recommend and I've successfully used documentation to change culture? First, because the documentation is an open window or an open Tory to jury code to your codebase. It exposes it to the world, but also it exposes your team culture a lot once you start integrating something that people don't really enjoy, like writing, documentation and start bringing the people back into the process.

A

Your jury still and now, placing jury, teammates and jury developer is in the correct mindset to be more mindful also about pull requests or more active or more mindful when reviewing code, people also start becoming more mindful when you are doing the sprints planning, because then you have to factor in the documentation, then it's go in dirt and a review of the documentation.

A

They can also help you to expose those code, smells and identify pirates that might need refactoring or are not as usable as you would like them to.

A

It also helps you to keep your institutional knowledge, so when that person that has not been documenting your codebase for eight or ten months or 83 years leaves the company it's because they decided to go to somewhere else, probably but jury during knowledge and your codebase safe, and you can build and dad and your reduce that card and that house of cards effect as well, and it also protects you against time. Turing.

A

It's in general, having all of this viewpoint on documentation as a first-class citizen in our eco development, also help people to be happier at work and also helps your user is to be happier when consuming your products, so both are more likely to stay around.

A

So under note there are: how do you start using dogs to change your culture or e to bring your people back into the process throughout this presentation, I have discussed three main parts, which is: what is the technical depth? What is what are some practices for documentation and how to integrate?

A

So for us to be successful in this process, we have to first accept that we have a problem and stop pointing fingers. We're probably gonna encounter ourselves in technical depth. A good exercise is trying to rethink about those bad decisions that led to technical depth, but not to point fingers at or blame someone, but to better understand how we can start repaying this depth.

A

The second step would be to use documentation to identify the suffering code, smells and pay technical debt. Make sure that if you're, using the mindful documentation, structure or if you are refactoring enjoy documentation to remove non-inclusive terms, then also you might refactor in some parts and again bring people back into the process and drive culture change. This is again the more you bring jury developers into writing documentation. The more you bring the personas and scenarios of the users into how to write documentation.

A

You also put your users in the plane in the first stage, so you can develop features that will be useful for them and meaningful for them in the future, and also people start becoming much more accountable. Your team will become much more accountable and sorry thinking about writing dogs, saying no to time turn probably saying now to unnecessary complexity.

A

So if you want to try and drive change again as one identify and accept or adapt use the dogs and bring people back, that is it. Thank you very much getting touched derice my twitter is, you can find it on Twitter yet check. There is also my email and these slides are gonna be available after this session. If you try to go to your hole, is going to give you a 404 at the moment and I'm gonna be also around github.

A

The univer is today, and tomorrow is, if you want to talk anything about dogs, CI, CD and machine learning, I'm happy to talk to you. Thank you.