So today we're going to be talking about documentation as UX or how you can rightfully write the right things Because alliteration is fun and not that complicated. So real quick, who am I? I'm the co-organizer of the st. Louis PowerShell user group

I'm a sometimes host of a Like a podcast chat show where I interview really interesting people And talk to them about what they're working on try to get their feel for the industry I'm a it says frequent contributor to open source. It should be like dabbler of open source partial projects There's a lot of stuff where I've added like a one-line fix or I've complained about something, but then my name ends up there

So if you look it's like nine or ten or twelve different projects But like I don't think one line counts, but github doesn't distinguish them. Neither will I I'm also a puppet software engineer. I joined their team relatively recently I work on the windows integration stuff the modules per primarily and at heart deep deep down

I am a documentarian. We'll talk more about what that might mean to you shortly So before we can really talk about how you can treat your documentation as ux We've got to define what ux is so pair of very smart humans define ux as all aspects of the end users interaction with the company its services and its products

You know it's official because it's smart and it's kind of italicized at the end like that. That's a pretty good indicator so Do you need that for like kly tools like your scripts and your PowerShell functions? Really makes sense to have like should you treat it like ux? Randall Hansen defined using your command line as something akin to submarine warfare

You're in an unfriendly environment any sort of breach in the system or error in your process could cause catastrophic damage So it's gonna be a little bit of a crowd participatory talk here So I want to know those of you who have blown up prod could you raise your hands for me? Yeah, that's pretty unanimous. It seems so like we've all done it like we're gonna burn it down again

Probably by the end of next week UX itself though is a really deep rabbit hole, so I'm gonna briefly touch on this stuff Understand each of these is a discipline in and of itself that there are like full groups of humans that go through and learn this Stuff and talk about it. I am not remotely smart enough to talk about most of this in sufficient detail

So navigation right so navigation ux What is it like when I start moving around in your application or your environment the thing that you've built for me to use? What does that look like how does it feel is it same can I get from point A to point B? Or did you drop me off in the middle of it with a compass and a good luck?

What's the structure like right so does the structure follow sensible semantics? Can I reasonably infer things about your product or project based on the things I've already seen do the names make sense does the stuff? Kind of flow from that so flowing forward from that. This is especially important for command-line tools as semantics Do the phrases and words that you use in your application make sense so for PowerShell

Good example of where they nailed this right is the approved verbs right so your approved verbs And sure that I have a very good understanding of what you're gonna Do unless you lied to me? Which you should never do if you've picked something that has an approved verb Use the right one and stick to what it says you're gonna do right

Visual organization doesn't matter as much to us maybe Visual organization is how does the layout sit? What does it look like kind of touches back on navigation? Can I get around it does it make sense? Does it flow in a way that humans are able to grok it and see it and kind of move through it does it follow? Familiar patterns color. This is an entire

I kid you not field of study Around the impact of changing colors across like how your stuff is going to drive an emotional response And whether or not that's going to be a good thing for your product I'm super impressed by that whole field of study, but I'm like way too dumb to follow it for the most part Usage right this is one. That's also gonna be really important to us

Does the way that people use your tool one of the things we talk about is the naive? Expectation of a user does that make sense does it bite them if a user does like the natural thing so a good Example is when you pick up a shovel right you pick up a shovel You kind of want to stick it in the ground It's got that little it's got the little lips on it, so you put your foot on that push down right well

If there was a spike there you probably wouldn't put your foot on it. Would you right? Sometimes we build tools that have spikes instead of lips like we should think about those things And then all of it kind of comes back to expectations all of this is driven around what users will expect and will naturally do outside of any sort of change in impetus a

much less smart person than the previous quotes Defines documentation as artifacts explaining something in sufficient detail I'm gonna kind of highlight this right here for a minute because mentioning stuff in passing doesn't count as Docs

It's actually sort of anti Docs. They're like you should think about security and then whistle off into the night That's that doesn't count you don't get points for that So there are three types of Docs to write we're gonna talk about the threefold doc model So real briefly you have reference Docs Then you have narrative Docs, and then you have concept Docs. We're gonna have slides explaining all this so don't worry

So three types of Docs to write and in your repos commit them. Why in your repos? I hear you asking so so loudly in this room Well, they should be in plain text Okay, plain text in a repository Okay So it can be diff so you can get a differential on what the text is over time

And you can see the history so we're gonna take a brief aside here Talk about how super duper important keeping your stuff in source control is this is markdown You may have seen some of this earlier this week and a couple of different presentations It's got a little bit of markup so this right here will show it in italics. This will be bold right

It's plain English. You can read it. There's no real problems around that it's relatively Out of the way right and it pretty much won the wars on what markup language we're gonna use for plain text You're gonna keep your code with your docs right You know write documentation. You're gonna keep it with your code, and I'm gonna hammer on this a lot today, right so

How many of you have documentation that lives in SharePoint or service now or some other place? Yeah a lot of you? Okay, what was the last time those were in sync with your code? Anybody have that currently in sync and was it yesterday that you posted? Was there one hand at the back that said you do have it all in sync

So come talk to me again in 30 days. We'll see how close it is right So the reason for this is that the further your documentation lives from your code the less likely you are to update it The harder it is to get your team to update it And the more likely it is that you're not going to notice when it gets out of sync if every time you change the

Code you have to change the docs for somebody else to approve that change. It's really really easy to stay on top of Relatively so real quick. You'll see here. Where are my docs one folder up from my source code Magic you'll notice that they get updated pretty much alongside each other

So diffing what's diffing so in the land of source control we talk about being able to diff our changes So you can check precisely how your stuff changed. Let's look at an example of that real quick So here in this first example, you can see there's some there's some green stuff here It doesn't really display as green. It almost looks white on my angle. Anyway, so the green to you

Nope, that's weird. Okay, whatever. So here's the change Like I went to so much effort to switch this out, I'm so happy I did So this is showing you what I added and you can see the little plus signs over here as well We added three lines to this document So that's important to be able to find is like okay. Well, he added these three things Okay, let's look at it something a little more complicated

so this change set here was when I ripped out all of the code from our main build script and Turned it into a bit of a more modular approach. So I just took everything that had to do with documentation I moved it out. So you'll see here. I have an include PS script root docs that sake so it all lives in that file now which is up here and you can see it's got a whole bunch of

nonsense and Then down here. You can also see that there's a bunch of stuff that's ripped with a little minus sign here these lines So what that is if you notice those mention doc see stuff The reason for that is that I pulled all that out of here. So it doesn't exist anymore Okay, so those are examples where like yeah, but I know what I removed and what I added

What if I change a single line, right? I don't know if it shows to you but this is a little bit highlighted here, right? So we've got the minus we've got the plus we see exactly what was changed So in this case, I added an alias to the project and it shipped out with it Okay, so if

You can get diffs and that's kind of magic being able to see who changed what when and why is Just it's out and out magic like it's it's the it's the secret sauce behind why everybody really needs to be using source control So here's the same three changes But now we're seeing what the reasons for them were so here we can see I added some options

Made a whole bunch of little changes here if all you had was the file got updated How easy is it to determine when it happened? Oh, and you can see exactly which person is responsible for all the terrible things I did Yeah, he's a bad person You can also see what happened in this change set I touched 13 files. I added 188 lines and removed 9

So this was like a net add to the code base The second one we separated the docs for reusability We saw that it ripped some stuff out and moved it had some other stuff added Here it tells you again what the reasoning for it was prior to this commit This is how things looked after this commit. Here's how they are now

And then the third one adding the git book plug-in thing that we saw where there was that that one line change In that single file you can see here again. Why we did it and what that was about I cannot stress enough how important a form of documentation that secretly is For future you and people who join your team People who have to try to work with your code or help you with your code. This is insanely valuable and should never be overlooked

And then here you can just see There's the separate the docs test so you can see when it happened who did it You can recover at any point in time all of that information All the change sets and and go back towards the code as it lived at that point you can see all those ones

Next up real brief aside, let's talk about scope and audiences right so projects have different scopes Some of you write docs that are for your entire team everybody who's doing operations has to follow these things This is what you do when the bad guys get in This is what you do when the really important database that pays us goes down, right? Sometimes you have a PowerShell module, and you just want to talk about like here's how you use the tools

And here's how you run the things and here's the considerations And please please please don't run this against prod without a filter because you'll burn everything and the DBAs will come for you And then the other thing we want to talk about is your audience all of your tools that you have have at least One audience, and they probably have more than one so there's an internal audience

Which are the people on your team the maintainers other ops folks? Business members who are going to rely on these things and there's external Facing folks so like if you publish PowerShell of the gallery Those types of people who are going to be using it external from your team who you can't like go to their desk and yell At them about stuff So we're going to talk a little bit more

Specifically about which ones we're gonna do for the purpose of this we're gonna focus on a PowerShell module because it's probably what most of you are writing So I said we come back to this what are reference docs well reference docs explain technical details And usage of a project so you're probably pretty familiar with them They're pretty much ubiquitous everybody has them

And you've probably stopped using things that don't have reference docs because that's unforgivable right if you can't explain What parameters are available for a product? I'm not gonna use it I'm just I don't know. I'm not gonna like fire a gun into prod for no good reason But they're not good enough right like just having reference docs isn't good enough for me to want to use your stuff

so for PowerShell Comment based help is your reference documentation right everybody in the room you're writing reference docs right raise your hands This is not this is not optional all of you are writing reference docs Glenn He was doing the hand waffle. I wasn't calling him out

About topic you can do reference docs here if you saw Sergei's talk earlier. I'm a bit of a heathen here I actually don't write about help For reasons that we'll get into around where it mostly gets read Platypus is phenomenal if you're not using platypus with your reference documentation You need to you really really do it's a huge quality of life helper

Allows you to take your comment based help and output it to markdown for further postings elsewhere If you're a believer in the philosophy that I don't follow you can actually keep all your reference docs in markdown But that makes it live further from the code and then therefore in my opinion harder to update

So Briefly I'm sure you've all seen this because all your hands went up. This is what comment-based help looks like right This is comment-based help whenever you do it from the help system you do get help something or other show window right same thing We've all seen these This is what it looks like when you convert it to markdown and output it to a website that your users can access

Whenever they feel like it instead of getting it from the prompt So you're able to generate this with platypus you don't have to write anything at all extra You just get this for magical free Narrative docs let's talk about these these are a different one if you guys have questions throw your hands up yell at me whatever Speak up so narrative docs they explain how and why users can or should do things or equally importantly should not do things

We've all built tools that will shoot your feet off and telling people how to avoid that's a good idea So narrative docs if you have guessed by the title use the structure of a story First there was a problem, and then someone had to solve the problem

And then they started making progress, and then there was a setback, and then they solved the problem and everything was wonderful These help you dig pits of success are you familiar with that term what a pit of success is the idea being if your Users rambling along just kind of using your tool. They'll fall into a pit and instead of spikes at the bottom It's delicious cake and wonder

It is not a lie in this case, sir so one of the sad facts Is that for? Technical documentation narrative docs are almost always written by outsiders I think I saw Dan Francisco's in the room earlier. Yeah, so Dan back there who I'm gonna shine lights on. Thank you

So Dan he's written some blogs About a whole bunch of stuff but That's sort of where narrative documentation gets done Is that people users of your project find it like it enjoy using it and they decide you know what I? Bump my feet on things. I'm gonna write a thing for future me so that I don't do that again like bear traps hurt

I don't want to step in them Which is not really good for us like as people who maintain projects. Oh, that's not true. It's great It's magic right somebody else writing your docs is the best thing that can possibly happen to you However, we should probably also be writing them it seems important

They're the most effective type you as a human. I assume. There's no lizard people in the audience All right well exactly one and the other one is I think he's talking to Congress today So they're the most effective type you're wired to hear stories You're wired to remember stories so a really quick way that we can kind of recap on this and prove at the point right

How many of you can quote to me some reference documentation you've ever read? No Okay, how many of you can quote a line from a movie or a particularly pithy tweet that you've seen or Something somebody said in a conversation anytime recently anybody

Was a few it's not a fuma get to the choppa Yeah, so see that's the point like your brain is wired for that like you're just built for it like there's nothing you can Do about it whether your mind works narrative is always gonna work better for you So here's an example of narrative documentation This is all written in markdown, so it gives you a bit of a better see you can actually see towards here

I have some code embedded in it You'll notice that it's this nice little syntax highlighting almost as if it cared about what I had had in there I'm just pretty neat So this is just the markdown. There's nothing magic about it you two can write it. I promise Here's the same thing Rendered right so we took that markdown

This is what people find on the website whenever they go to view the documentation Which if you notice is more friendly to read and it has hyperlinks and stuff like that. That's pretty neat So let's talk about concept docs this is kind of my Favorite thing and or pet peeve depending on how you look at it, so concept docs they answer specific questions

Right we're gonna talk about what those are here very very shortly They're the least common type you may have noticed almost nobody writes these they're pretty much missing from everything You'll see them sometimes in PowerShell stuff Or they'll do like about some sort of esoteric thing to do with your new module because it's confusing and different Most of the time we just go Which is not a good answer

But if you want mandatory Good user experience if you want people to fall into that pit of success if you want people to be happy and love your stuff Walk up to other people and be like oh have you tried playing with this tool. It's great You got to use it, and you need to have concept docs So what are some of those questions, and how could this possibly be an important thing that you'd have to do

What questions could somebody possibly have about your project? Yes your project that they would need to have answered Anybody here ever done something and somebody else in the team's like I don't like the way you did this Why'd you do that? I? Heard chuckles I get you I'm in the same boat right so why you chose a specific design if anybody asks you Why'd you do X instead of Y more than once that's a hint that you're missing a concept doc

How does this internal component work? Why was it used? You know I see that you guys have built this stuff on Ruby, but did you consider rewriting everything and go? Yeah, we did, but like nobody writes. Go so why would we do that? When should I not use the particular feature I talked about this a little bit earlier, there's plenty of times where like

Everything has good uses and bad uses right like you shouldn't do like not everything's a nail And if you're trying to use this thing like a hammer you're eventually gonna hit your finger or somebody else or get fired Don't do that so a good example of this is if you have a tool that'll Shotgun data at a series of web farm nodes

Maybe don't run that in prod or don't run it during certain hours right or if you've got something That's gonna suck up data and display it in a report make sure that you're doing some scrubbing before you do that These are the types of things that you need to be answering for yourself internally right, but for external folks, too What do I do when I'm implementing this project in my environment how many of you have picked up a new product and it's

Time to like get it in place, and they're like yeah, so here's how you do it in dev And this is something something certificates, and then good luck securing it and getting it working by There's a lot of enterprise Using the term loosely products that do that to you right does anybody ever implemented something and then realized that their implementation was wrong

And then what are the best patterns and practices and which ones should I avoid so same sort of thing like Yeah, you can set it up with no encryption, but should you ever know Like you should encrypt everything between all your endpoints right everybody's using HTTPS everywhere

No, yeah, see. Thank you Tito. Well. You're at Google of course you are Yeah, you get yelled at very loudly So another brief aside internal versus external most of the rest of this documentation talk We're looking at stuff is gonna focus on your external audience But keep in mind that your internal audience is critically important to you right like you ever gone on vacation

Been confused when you came back like something's changed. You don't know what or why it's like well I was trying to run the deployment script, and it all caught fire. Oh, yeah, I know we updated that on Thursday You didn't know No So you've got three types of documentation right, but there's uncountable forms, and I'm not kidding right

I literally didn't count these you can if you want So there's centralized docs is the stuff. We're all really familiar with right static sites wikis confluence service now SharePoint GitHub and GitLab templates for those of you who don't know you can use these little meta document things inside of GitHub and GitLab so Somebody goes new issue it fills out some basic information for you, and it proved it provides like a layout for like

What's your OS? What's the bug here's where you should upload things send me this link paste the error messages into this like Like paste bin type area whatever so those will Kind of funnel people into like your expectations around your project, and you'll help you get some good bug fixes and stuff

Emails how many of you write emails to users when things catch fire anybody you all avoid talking to users right okay good No So emails to users and to other people on your team right so anytime you're explaining something about your project That's documentation whether or not you treat it that way it is right you're communicating technical details to another human

You're explaining something so if you have canned emails for like hey I was trying to log on but X went wrong and you're like well. Yeah, you need to clear your cookies Send that email. That's a good documentation. You think should think about maintaining some of those that way So chat chats documentation sure so slack teams matter most hip chat stripe

Is it that replaces hip chat soon? So any of your chat apps IRC if you're really old-school The advantage here is somebody asks a question on your team or maybe what's one of your users or customers I say hey, how do I X? Somebody's gonna answer that question like oh well the way that you X is you Y and you Z right and then there's like

Well, I don't understand how you Z Conversation comes out and there's a lot of explaining a lot of link sharing and stuff and then tomorrow morning you come into work Somebody else comes up and say hey, how do you X? Well you can search and Find it for yourself. That's not what you say, but that's what you mean Then you send it to them and then all of that information is captured searchable and available

That is probably for me the like the best part about these tools Being able to go back and find all of the answers that you've already shared, but again you've documented processes not formally right But you've done documentation. You've got it down. You can convert it later. You can just point people to it Forums and Stack Overflow I already know the answer show of hands who uses Stack Overflow right everybody here is copied code from it

Right into production before right? It's what we do that's why we get paid the big bucks Forums that sort of thing same sort of thing right somebody asks a question you answer it if your team is putting products out there This is more for for vendor II side of things or if you work on things that have bitten you before

Being active on Stack Overflow is a great way to build up Informal documentation that people can use because it has really good SEO, and you don't have to pay for it You just let stack do it Blogs we talked about narrative documentation Dan's blog Glenn's blog how many of you have a blog or read blogs?

Right all of you read blogs. No hands should be down. Okay. I know you do So those are also documentation Mostly for people who didn't pay them to write the docs which I think is pretty neat At least for the companies who are getting them to write the docs for free Metadocuments we're meta documents commit logs every time you make a change in source control

And you forward it around you have a commit log it tells you exactly what changed it when that's where we got that diff information That's where we got that history information tells you who did it why when when exactly what that change was right that stuff is Documentation of your design decisions the patterns you followed. What was important at that point in time

There's a ton of information to be gleaned from this stuff Issue comments does anybody work either internally so it doesn't have to be publicly available, right? But like you have like a private github or VSTS or TFS or get lab or whatever right? Do you use the issuing system in there? So for those of you who are lucky enough to be allowed to use that or JIRA right it's the same sort of thing

We'll cover that in the tickets thing that comes up next So somebody says they file an issue to say I think your project should X or right you know I was using your script and then this thing happened, and it's terrible and you burn down prod And this is all your fault and like well had you known not to run it without a filter You'd have been fine What it really means is you need to write a doc But that explains it and says where it all came from why these things had to happen

Shows you the history of why you made decisions Which is as important as what decisions got made right come in on Thursday all the deployment script changed. Why? Probably it's in these two things right now that information lives somewhere and Hopefully it also lives in ticket data and change logs which we'll talk about too So ticket data is the same sort of thing

It's just another place for it to live anybody use JIRA and or service now right similar tools remedy whatever Somebody files a ticket they say hey X is broken. I need this fixed you say okay I ran script Y and here's where it went and here's how it worked all of a sudden You know have some data some documentation explaining what to do when that happens again

Or what not to do that also happens right like we tried to fix these things and we're sorry Licenses these are very important if you have work that you ever want another person to use ever Include a license MIT is my preferred licensing because it's super open and available you can do Apache or whatever you want

Talk to legal, but if you have work out on the gallery or anywhere publicly right now, and you don't have a license No one's gonna use it Especially anybody that's working at a company they can't they'd be literally are not allowed to use a thing without a license Even if you say publicly on Twitter hey, man, it's fine. You can use it, bro. It's all good They're not gonna do it because that liability is really really scary to legal so put a license in it takes you 30 seconds

They're templated out. You don't have to do any extra work Change log so for those of you who have code how many of you have a comment section at the top of your Code that says what your changes were Yeah, let's not do that. Let's keep change logs these things are magic right so what a change log is and the preferred format

Is keep a changelog org keep a changelog org you go there find it There's a really good standardized way for you to do change logs really readable Really useful we've been adopting those at puppet, and it's been pretty great Can't strongly recommend them enough. There's plenty of information detail around it

So the reason that so if your commit logs and your issue comments in your ticket data are for you the maintainers, right? What are the chances that a customer is ever gonna read your commit history? zero No one is But this tells people When I took off on Thursday And I came back and then there was a new release of this tool what changed and why and do I care?

Right so if you're following good versioning and all the other kinds of stuff your change log should show you exactly what changed and how much? I should care about it Contributing Again if you want people to work on your projects include a contributing doc it'll take you 30 seconds You can do like I do and steal from Brandon Olin he's actually giving a talk in another room right now

He's got a nice little contributing doc There's a bunch of different ways you can get them so what these do is they ease the path towards working on your project or working with you on tools Contributing doc says hey Here's the things I expect from you like if you add code add tests if you add code that changes parameters or whatever add Documentation here's how you file issues. Here's where to go here's my expectations

Here's a code of conduct whatever all the information about how other humans can work with your humans right have your people talk to my people That's all covered here. We're really not done yet. I wasn't kidding like there's so many forms of documentation Right so Documentation in your code right how many of you have got a comment says I don't know why this works But it does please don't remove it right. Yeah, that's a lot of hands. I wrote that earlier this week

So let's talk about a couple of different types right tests if you've attended any of the test talks this week You might have noticed that the tests describe expected behavior, which you might also recognize as documentation Right tells you what you're expecting or what might be dangerous

Tells you when you're looking at code, and you see the tests What are the things that are important about this project? What are the things that are dangerous about this project, and it kind of covers both of those? Code comments like we talked about like everybody's got them or you should right Do yourselves a favor specific type of code comment you can do whenever you do a regex capture

Show what the thing is you're trying to capture in a code comment above it like this is meant to match this thing Because future you will not remember In line documentation so PowerShell's got comment based help Ruby's got these little described blocks pretty much every language has these Use these don't ever fail to fill these out. That's pretty inexcusable for you long term. It's low low hanging fruit to add

But that way your documentation can live really really close to the code that you're writing But we're really not done yet. There's non-written docs right so what are non-written docs We don't think about these very often so far. We talked about stuff. You can do it a keyboard audio documentation Like podcasts and voiceovers, so we actually have an attendee here today

Who isn't able to see right? And I don't know if you've ever listened to Siri try to read off something to you But it's not a super good experience so consider having someone who goes through and provides a really good thorough experience reading documentation Right it's a little thing. We don't really think about it

It's not as expensive as you think it is and it's super super useful for inclusivity Podcasts how many of you listen to podcasts anybody good number of people Yeah, so the advantage. I'm holding the water instead of drinking it It's a good thing my podcast is podcasts are a combination of narrative and concept Doc's

People give on the fly no one writes them, but they talk a lot right like remember that time We did that thing and it hurt. It's a concept doc that lives in a podcast so It's also a lot easier to get engineers on your team to get together and talk and like share stories and stuff than it Is to get them to write those things down and then do internationalization around them and all that's really really hard for them

So you can convince them just to kind of like talk and that'll work, too video So if future you is watching this then you're getting a form of video documentation around documentation But it includes tutorials recordings lectures, so Good examples include like plural site courses that sort of thing Gives you a really good insight into how something's supposed to work or how you should use things

Live which if present you is here, you're currently experiencing Other forms include in addition to like you know talks and stuff labs labs are a phenomenal form of documentation It explains what you think is important about your project or product and how people can use it where the bear traps are Pretty much every lab is a don't do this section, right?

And then Q&A which will hopefully get to at the end of this is similar So we're gonna focus. I guess we might have time for my demo sweet have I been breathing there many noticed I know I'm sweating, but I'm definitely breathing. I did breathe twice. Thank you so much for me So we're gonna talk a little bit about documenting a PowerShell module using the tooling that I have called documentarian

Which is just a PowerShell core module I wasted a lot of time making it run crossplot even though four of you will use it not on Windows But it works So we're gonna talk about documenting it So what we're gonna do is we're gonna use plaster to scaffold out a PowerShell project And then we're gonna go ahead and we're gonna use

Documentarian to scaffold out the docs and see what that looks like with that experience will be for you if you choose to use a tool that you should use Not that I'm opinionated. So the modules documentarian you can find it at getlab.com slash documentarian slash documentarian or Forward stroke depending on who you ask. You don't need to see me import but the important thing here

You'll be able to see shortly is that there's a line where I export a variable not many Projects export variables, it's not real common The reason for this is there's no way for you to do searching on plaster templates And you'll see how super duper important this variable is shortly. I promise you it's gonna be really really useful for you

So we're gonna get the plaster template This is us getting that basic template so that we can invoke it So get the plaster template where it matches the new Marshall manifest module and then expand the property on template path And that'll give you the path to the template which you need to do Invoke template or invoke plaster Right. So now that we've gathered it. It's time to go ahead and scaffold us a PowerShell project

See I saved it to that variable in the last one. We've got it here It's gonna ask us a couple questions. So plaster is a tool that will ask you questions and scaffold things out so it asked us for You gonna reset nope good enough we're stuck with it. That's fine. So it asked

What module name we wanted it to be we chose summit here it asked what version we wanted We set it at the default and then it asked, you know, did we want to have it set for VS code? Which is what I'm using here. So now we're just opening it up. Take a look. It scaffold it out Just real basic if you saw Ron's talk earlier Rob's talk earlier. You probably saw some plaster II things. It's the exact same thing here

I didn't change anything any questions about plaster No, totally confusing enough juice Good You don't need to know how the magic works, it's not all that important Because the real magic is in getting your docs So here we're doing the exact same thing invoke plaster But I gave you that nice little thing so you didn't have to find the template discover it and everything

So here same thing. It asks a few questions. What's the name of the project? What's your brief description here? We say project with quality of life functions for some attendees Ask me how I knew it would say that watch how fast I type to you and that's great So I'm the primary author and I'm the person that has the legal rights to it I guess and

Then here you'll see it scaffold out a whole bunch of different files and folders, right? So all of these things are also gonna be in there We go back you look there was the the two files that were there though Accompanied by a readme a changelog a bunch of other stuff The description ended up at the top of the readme kind of just does a little bit of basic help for you

But you're gonna have to you know, write documentation like I can't do that for you and do some of it not all And then it includes a build script for you This is probably the thing you're gonna find most useful is it includes a build script that will allow you to do live previews of your documentation in

Your browser and allow you to do builds whenever you go through CI if you have that And it scaffolds out all the files and folders and all like the kind of useful quality of life stuff So this you should only have to do this once whenever you spin up a new project or you want to add docs To an existing project here. It's gonna kind of fly through it's doing that live preview of just the base So all it's done is scaffolded out the docs and right now

It's going through and just building the website. So then Yeah and click Good, and then this is the whole thing scaffolded out, right? Isn't that magic?

So it just fills out a couple of base things Notice it doesn't add reference docs because there's no functions or anything like that yet And that's the the demo piece If you're interested I can show you what the actual documentation and all that looks like afterwards, too So let's talk about some quick takeaways right when we talk about docs a little bit So your docs need to live as close to your code as they absolutely possibly humanly can you should write more than just reference

Docs, but hopefully you're at least writing reference docs the words you choose matter The way that humans are wired the words that you use in your documentation are gonna make a really big impact on how they're gonna Receive it and how useful it's gonna be for each person To that effect you want to think about whether or not your product should have gendered pronouns whenever you're explaining how things work

If you're gonna use he him everywhere, like I guess the only people who use your product or guys Just probably not true. That's I think I've heard 50 ish percent of the population doesn't do that Something around that. Yes. I don't know. I'm not an expert clearly

So Your words matter the word choice matters You want to think about who your audiences are and what you're writing for you need to pay attention to it It really doesn't take that much effort write and design specifically, right? So same thing you have a particular project a particular product. You're writing it for specific humans to use right? It solves a specific problem. It's not the end-all be-all of everything always right because those projects are super hard to maintain

So you want to write and design specifically the same way that you'd write and pay attention to your code and make sure that Mates its particular requirements you want to do that for your docs, too And you don't want to forget how many different forms there are I spent like nine slides covering that So if you could not forget that part I'd appreciate it and then the same way that you treat your code you iterate right how many people have written something?

Published it and then it was just good forever. It never had bugs or problems or anything anybody Not seeing a lot of hands go up. Yeah, that's suspicious So there's a bunch of resources here I have a project I talked on last year called needful docs that explains sort of the Same thing nice and punchy you can send it to co-workers

Explains the threefold doc model all this stuff's posted afterwards too. You can check out on you follow me on Twitter You'll find it all right the docs. I think they're like event is almost always out of Portland So right the docs is an amazing conference where you can get together and listen to people talk who are super smart actual Documentarians like people who professionally get paid dollars on purpose to write docs will share how they do this and how it works

And it's awesome Does anybody know who June blender is you ever heard the name like once or twice or 35 times? So she still has some incredible stuff up on github She's not doing as much with PowerShell now, but if you've never checked out the PowerShell help deep dive

You need to it'll help you write a thousand percent better PowerShell The markdown guide is just a real quick like five-minute walkthrough on how you can write markdown and what that syntax looks like I Impost on five tips from improving your technical writing and documentation human readable stuff That'll help you out help you kind of get to a point where you understand better like

Some of the concerns around writing technical docs that I just couldn't cover here like something. We didn't talk about internationalization That's hard Gender neutral technical writing there's another thing so you're concerned like well. I don't know how to change how I write Let's walk you through it. Just some really simple kind of quick pointers

There are still more resources Hacker noon is writing good documentation super useful. I have this bookmark that check it out pretty frequently Jacob Kaplan Moss is pretty well known in the technical writing circles around the stuff that he's done around writing good documentation I think he's one of the original members of write the docs This is a really good resource all this stuff like nothing I've told you today is new or revolutionary like I certainly didn't make any of it up. I stole exclusively from smart people

So this is the part where you get to applaud and or heckle me You can find me on Twitter at barbarian KB LinkedIn get hub get lab everywhere else on the planet at Michael T Lombardi If you take a look at the things and stuff sucks

Let me know yell at me complain the louder you complain the more likely it is that I'll close won't fix That's an open-source joke, I'm sorry Thank you though, thank you for coming out. Thank you for sitting through this while I kind of sweat slash speed yelled at you I appreciate your time Any questions