Okay, that's my cue.
Let's talk about a party on the team.
Oh my gosh, you've looked me up.
Hi, everyone.
I'm James.
I hope you can hear me on the recording.
I'm going to sit down to talk because I want to use both my hands to hack for you.
So don't worry, I'm still here.
Don't be afraid.
And I'm going to try and talk quickly and make this energetic and fun.
You have any really questions because I've lost.
You just let me know.
It's my first time in the docks room.
So I don't know the audience super well.
I come from the automation and can figure management hacker space.
And so I'm going to try and give you a good docks talk.
So yeah, I'm trying to get better at writing docks because I'm kind of really
shit at this.
This is just a quick video from my hometown in Canada, which I think is really funny.
And we're normally pretty good about snowing everything, but it was an icy day this day.
And so this bus had some trouble.
But then this little taxi, how little bit of trouble, too.
And I'll let you watch this.
It's much easier all, yeah.
Boom.
But that's okay because we have help for this kind of situation, which will come shortly.
I have 25 minutes, right?
Yeah.
I'll lie about talking about docks.
I'm just showing videos today.
But here comes the bus.
The buses are, and then watch this number two, here comes number two.
Oh, yeah.
But.
I'm not very creative at coming up with material and this makes you laugh.
And then how could we make this even better?
How could we make this better?
So, this is a truck to put salt down to make it less slippery.
Do you find several people up there?
Boom.
Yeah.
So anyways, just for my, I'm a hot guy.
I work on automation, config management things.
It's a very misunderstood field.
There should be sending patches, but he hasn't.
I write a blog called the technical blog of James.
Who's write my blog?
Just raise your hand.
If you haven't, raise your hand.
So I seem really popular, please.
Yes.
Thank you.
Actually, if you're all just by training, I have this stock interest sites.
So I guess maybe you've seen this.
I work for this weird company right now.
They're very kind and they paid for my travel here.
So I'm quite thankful for that.
We don't really do anything about documentation specifically, but do tack and whatnot.
And if you're looking for a job, we're usually hiring.
So how about have a look?
So these are not my opinions.
Obviously, these are my opinions on my employers, blah, blah, blah.
Bad jokes and so on.
This image was stolen from the internet.
My whole life that I've been kind of writing software really, really struggled to write
docs and to get them up to date.
So anytime I can use tools and software and automation to make this easier, I'm like, I'm there.
And yeah, the, the doc world is, for me, it's always been kind of terrible.
And, and do we, do we want bad docs?
What?
All right.
Thank you.
So this is, this is my nope guy who's just, um, if you see the weird image quality,
this is because we were office has a bug, so if any of you are, we were office hackers.
I don't know what's happened that broke.
So yeah, we don't want that docs.
And so, um, so this is the project I work on.
It's an open source thing.
I've just been running it myself.
If you really want to stick around, you can use it, come, come see me at the end.
Do you want to see a quick demo?
Yeah.
Okay.
So I'll just show you in this space.
This is not really what it's about.
But basically, um, you just, whoops.
You just, uh, turn down that beeping.
Um, we just have this tool, um, something like, for example, hello.
It's a declarative way of doing stuff.
So if you run this kind of file, I'll show you exactly what that code looks like.
Is that big enough for you to all see?
Can you see that?
Let's make it a bit bigger.
So basically, we declaratively say how the world should look, right?
So in this case, we say we want this file that exists in this path to have these contents.
It must be the case.
And so we, whoops.
My microphone's phone.
We, we, um, we run the tool with that kind of special code.
And then we'll look over here.
We can go and check that file.
Um, make that a bit bigger too.
M.T. Hello world.
And it, and it's there, right?
Um, and just so you can see that I'm not treating.
We can actually say something like, uh, hello world.
Well, two docs people from me, right?
And we can just run that again.
Just chill this.
And you'll see that the file doesn't even have those contents, right?
But the, this is what many tools do.
But the cool thing about M.T. is it's live.
So if you, for example, deleted that file and counted the file,
it comes right back, right?
So you can delete it.
It comes back.
It's silly.
Uh, kind of a knowing game you're fighting with the computers.
Kind of like AI.
Um, but any so fast, you can really even do.
And then it comes back very quickly.
Now we can do this for virtual machines and blah, blah, blah.
I'm also bad at marketing.
Um, but just really fun.
You can even go really fast.
Uh, like a top speed on Linux and boom.
You can see the tool keeps working up.
blah, blah, blah, blah and fixing the state, right?
And, and that just goes on forever.
So, um, and then the cool cool thing, because this is cheap.
Um, we can actually express time as a thing.
Um, and I'm telling you this for a good reason.
I'll get to talk in a second.
So I can actually write slightly different code.
Um, just really quickly.
Oh, my god.
This isn't so well.
Uh, sorry.
There's no syntax highlighting.
But we can actually express streams of time and pipelines and documentation,
pipelines and hinting and model these over time.
And as time flows through this function here,
it goes into this variable, which goes into this template.
And then the file should change over time.
Oops.
And so if you, um, oops.
Can't type properly.
As you see, I'm running this over here and in this file here.
So we can see this file that I just created for this demo.
And if I just cat this, you can see that every second.
I'm just pulling the file to see what's happening.
It's changing over time.
So just data flowing through pipelines to new way.
Um, everyone doing docs is going to be using this in the future.
So you've had a warning.
Okay.
Enough of that.
You want to see more real doc stuff?
Yay.
All right.
Who do you all like hackers and software people?
And who writes no code at all?
Raise your hand.
Who wishes they wrote no code at all?
Okay.
And then the last question.
Does anyone know what an AST is?
If you do raise your hand?
Um, don't be shy.
Um, I really didn't know what this says very recently.
Um, and just here's the rough like background of my talk.
So writing docs at all is difficult.
Um, many languages have a way that you can put in the comments.
Write above the function a little stuff about what it does.
Um, but you can use that comment space or any comment space in your entire code base.
Even if it's in file just with docs to put source code in.
And that is along with the commit.
So you have some traceability about where did this happen?
Where did this start all that stuff and so on?
Um, and you can, you can just cheat.
Some languages have built in ways to take those comments and put them into documentation.
But those are documentation about the program.
Right.
You can also, you know, misuse that that functionality with a very small amount of code to generate custom docs that are for your user as opposed to the programmers of your software.
Um, honestly, this is way easier than you think.
Um, I'm not a huge like like AI large language model supporter.
But finding the API.
So the functional programming interface that you use to talk to these ASTs which we'll talk about.
Um, models are very good at figuring out these docs, figuring out these APIs.
So I actually cheated instead of spending two hours trying to learn how to parse the AST, which we'll get to.
I just cheated a little bit and got some hints from a large language model.
So don't be shy.
Um, it can help be a net benefit.
Um, and so what I typically, the model I, I've chosen.
Um, and I think you might like this model is you have your code.
You decide how you want to store your docs and your data and so on.
And that's really up to you.
And so I would write a small script that takes that out into an intermediate format like JSON.
And then that JSON file can then go into different tools.
So like a PDF generator or website and so on.
And so you have to kind of think of that intermediate format and pull it out.
In my case, I use, I have a website run with Go Hugo.
It's a static site generator.
She'll show you.
And that's what I used to then read that JSON.
Does that make sense or you confused already?
Who's confused?
Don't be shy.
Okay.
I'm going to pick on you.
Careful now.
So do you want to see a demo?
Yeah.
All right.
Thank you.
So, um, so let's just start off here.
Oh, there are my demos.
Um, so here are, I'm just going to show you the website.
You can actually, um, even go to this website here.
So you can see it's all live.
But just to make it a little faster, so I don't have to break the live website.
I just have a local copy running here.
And this very sad sad doc's link has some reference.
So in my software, um, it's software.
For developers and other people.
And we want to give some reference.
So they know what, um, functions and resources.
What we call them.
They're available.
So I have this one page for functions.
Another for resources.
And you can see here.
We have this kind of list of all them at the, on the side.
You can click and see some stuff about this.
I'm not a web developer.
This is not, you know, but if you are.
Patch is welcome.
Um, and so.
So what we actually do.
Um, so here's the split function for example.
Uh, if we go into here and we'll get split.
Um, and you can see that this, this comment here basically comes from this function.
Right.
Is that match?
All right.
And just to prove it, I need a magic word.
Someone.
Do it.
All right.
Let's do it.
If you want to hack with me, it will be as fun as can be.
Uh, let's see.
Be rhyming is fun.
Um, don't.
Let's think.
Don't run.
All right.
Fine.
Docs.
2025.
Okay.
So we're just going to save that file.
You're like, what is this guy doing?
You see a crazy person.
Um, so we just saved that file.
And then as part of my tool itself, I have a little.
Uh, my tool is called MGMT.
Can you see it at the bottom?
I can make that a little bit bigger.
Um, so I just run MGMT.
I have a docs subcommand because I can just do whatever I want.
And I can generate and put the output.
Let's say in temp.
Docs.json.
Okay.
So I run it.
Um, when I'm developing docs, it actually gives me some morning.
So for example, I have some fields that that don't have documentation
Description.
So it's like saying, hey, you didn't comment this.
Um, that's okay.
Cause these ones that don't want really commented.
And then it wrote this file.
And then if you want to just cat this file and look at it as.
As json, you can see it's like this big,
norally horrible json file.
Right?
Makes sense?
Json ugly, but useful.
Json is useful in this case because I'm not really editing by hand.
Right?
It's not human.
It's human flexible, but not human.
Really readable.
Um, and so I can do that.
Um, and you can see at the top level, I actually have like a version
field, which is just the get hash.
So I can have this unique.
Um, field.
I have a big struct for all the resources.
And uh, functions, some way through.
You see how all the functions as a separate thing.
Um, and so that's that.
Um, just to get really, you want to get really nerdy and technical.
Yeah.
Anybody else?
So you can actually see in the code that I wrote.
And this is all open source all on, uh, on GitHub.
It's actually the whole thing is like not even a thousand.
It's like 800 lines with comments.
Docs.
Um, it's really quite simple.
The whole thing is just really this data structure called output.
So the top level field version resources and functions.
And then in the future, let's say there's a different aspect of my program.
I want it to opt to add.
I can put like, you know, thing here or whatever.
Um, and then so the resources are all kind of this set of fields.
And then, uh, functions are this set of fields.
Makes sense.
Um, I'm glazing over to a little bit, but it's, it's very,
very easy once you start playing with it.
And if you're doing this and you're stuck just joining our channel,
and we can help walk you through it.
So we have that.
We generate the JSON.
And then what do we do is we go over here.
Um, and we copy the JSON to, uh,
I think it's data.
Uh, where is it?
Uh, yeah.
It's got to be in data.
Yeah.
So we're going to copy temp, uh,
docs.json to docs right here.
Okay.
And so that you can see is, is, is, is, is, is, is, is, is, it's not sort of get actually
exciting.
We made it.
And then we just run the the site generator again,
which is this fun command, um, and so this statically generates a copy,
but it's just keeping it locally.
So I don't have to push it online.
And then if we go here and refresh, refresh this page.
Oops.
You can see, um, you can see all the stuff is changed.
Oh, oh.
Oh, man.
If you come to my other conferences, I can show you some rules.
This is, I can show you some really hard code demos.
This was easy.
I didn't even study for this.
Yeah, and so obviously, I've chosen what this looks like.
So I've chosen the data structure to have all this data.
So I have the signature of the function here.
So if I wanted to change that to something else,
like C-ball, this is our type signature.
You don't have to know what that means.
And I can go through the whole dance again,
if you want to see that dance.
I can just go there.
Let's just copy that over on this again.
And you don't have to re-run it.
I'm just doing that because it's easier to fall
than switching terminals.
And you can refresh this.
And did I refresh it?
Did I copy it?
I may have, maybe I didn't even save it.
Should be saved.
We can make it work.
So it's output those docs.
Copy them here.
Should work.
Doesn't you get your money back?
I think it's actually caching something.
Did you like get commit?
No, but it does update.
It definitely works.
I actually wonder why that's not working.
Now I'm more curious.
But so we can actually look at the docs.json file,
split, split.
And this is why it's OK.
Let's see.
Let's be good hackers.
Let's see, split.
Strings.split.
I don't know why I didn't come out.
That's interesting.
That's a mystery.
But yeah, oh, it's probably because it
wasn't a valid type or something.
Let's try this.
That's probably why.
So if we modify it, I'm modifying it, not split.
Yes, I know.
Oh, I know why, actually, because I didn't
excuse me.
I didn't compile it again.
So that's exactly what I didn't do.
So I forgot.
I have to compile it because it's part of the generated code.
So that's actually the bug.
And so then I run this.
And then I can copy this over.
And we can run this server.
And now it will definitely work.
And there you go.
So now it's seen.
And this is, yeah, I want to like,
soapbox for a second.
I see people do live demos.
And something gets stuck.
And they freak out and they're like, ah, don't get
freak out.
If you are giving a talk, you are the hacker.
Like you can do this.
So just hack it through.
Like imagine if you went to like some concert,
like you saw like, I don't know, like Drake or something.
And he's like, ah, I need to stop playing.
If you're near, like, put on a show, like don't be shy.
Give life demos.
Yeah, so that's how that works.
We'll just go back to these boring sides.
Do you do?
I think I lost my place.
Hi, I'm James.
Physiologist, Barbara.
Nope, no, demo, demo, docs, docs, docs.
Apps aren't abstract syntax.
So just some foundation of about foundations about what
this work.
Don't be scared.
It's scary.
It's just a tree structure.
Imagine like at the root of a tree and then branches,
it's just the kind of structure that the programs have.
I just write all this stuff so you can see it.
And most modern languages store the comments in this AST.
They look typically like this.
This is just stolen from Wikipedia.
You don't have to know the specifics.
But basically just think about in your program,
there'll be a structure with parents and children
and so on, and the comments should be in there somewhere.
And it's very easy to parse these.
It's even I can do it.
So you could do it for sure.
The parser, so you'll need a little parser.
You'll need a small program to go through that AST.
You don't have to write the parser from scratch,
because typically the language that your parsing already
has one, because they're using it for its own code.
So don't write the parser from scratch.
Just use their library.
And just keep in mind.
You don't only have to take data to build that data structure
from the parser.
You can also have internal APIs in your program.
For example, my type API that you saw.
And that's just data that's in my program
that I run and I use that data too.
So anything you want, you can just write a function
that gets you that data, and then have that all
build your struct.
And so you build that single struct.
I showed you some of the code.
It's super simple.
Again, all of the source if you want to go look at that.
This is actually slightly tricky.
But yeah, it was a few hours work sort of thing.
I told you about this intermediate format.
I find that very useful because now I can say,
hey, I'm shit writing this website,
or you want to make a book or something else.
Other people can parse this, and you
can have more formats all from that, that same source of truth.
I love the single source of truth thing.
I kind of showed you this as well.
Static site generation is a beautiful thing,
because I hate running sites and having
a server where there's all sorts of free hosting
that I kind of steal from the internet.
And I showed you how I run this as well.
And the lovely thing is that people that
are not hardcore programmers can help out with my project.
You can write docs.
You can send pull requests to the box site,
designer, make it less ugly, and so on.
I showed you some photos of this.
All of the links on this website, which is online,
they have this view source link.
So you can actually see the documentation,
see a bug, and go right to the source code,
where that is generated from.
And so I generate those links as well.
So if you see a problem, fix it.
I would love that.
Because I definitely want to write a code.
Stringcat function, cat strings, like some things like that.
So that's how that works.
And so on.
So testing, here's a really cool thing that I do.
So every time I have a git commit,
it goes through all these automated tests.
And in fact, the script itself will check some things
about if the documentation is right.
In theory, it could check spelling, but it doesn't,
but I spell really well.
So that's great.
And it runs these tests.
So even if someone sends a patch,
you can test your docs as well.
Some people will put like, if you say,
like, some really bad word, it will fail the test,
or you can use your imagination.
So how much time do I have left?
Let's see, I've got five minutes.
All right.
I have a friend of mine actually named Ellie.
She has this website, Ellie.com with two eyes.
And she actually did the go-hugo work for this,
because I knew how to do it, but I was crazy.
And I was like, hey, why don't you do my doc site
and go Hugo?
Because she's running more Go Hugo stuff.
And so if you want some Go Hugo work done,
you should a great job in get patches,
I reviewed the patches, and then merged it.
So that's five stars.
Hi, Ellie.
Is this recorded?
Where's the camera?
Where?
Oh, hi.
So yeah, if you're interested, if you're interested,
have a look, there's a find it hard to find, actually.
I've been wanting something to do Hugo work for a while,
like someone who knows Git and these kind of Linux technologies.
I find it so hard to find people.
So I don't know if it's just me, bad at searching,
or whatever.
What's next?
In the future work, I really need to write some
getting started guides for my tool.
I've been lazy, I've been bad at focusing on new users.
So I need to do that, but if you're interested
in playing with MGMT and helping write stuff,
I'd love that.
We need to actually version the docs,
so that as new versions of MGMT come out,
you can click and see which version these docs are for.
So the latest version is correct.
And we need to actually start writing more architectural docs.
Currently we just have standalone lockdown files,
but I plan to move these into the main source tree
as code and then parse them out.
So just like about how internals work,
not individual functions and stuff like that.
And translation is the thing that I really
need to get on and integrate the plumbing for translation.
So if you speak French, keep out falsa, as manual,
Battlesky, you show, anyways, whatever.
So just any languages I love trying to learn languages,
and I'm shit at a lot of them, but I'm trying.
And what will be really cool is I should actually automate
my docs pipeline with MGMT,
instead of doing it manually as I have been doing.
Whoops, but yeah, there's too many things to do.
I didn't really want to be a business person.
I don't want to do sales or consulting
or any of these things.
So if you keep plug, but if you want to help do MGMT stuff,
I'm happy just running an MGMT project,
but I need people who are good at making customer documentation
and selling sales and stuff like that.
So if you want to job doing that,
you make the money, you give me like a small percentage.
I get to be an awkward nerd, you get to be a super sales
consulting hacker.
Sound good, right?
Binder, it's good stuff, right?
Binder is a brilliant guy.
He wrote some really patches, and then got busy with life,
but he's coming back, Chris said.
So yeah, if you really just randomly are running
to help do free software, if you don't help me,
then I have to go get money from investors
and do like Prytar shit, which sucks.
So don't be shy, let's just recap.
He's just recapping his pen.
It's my lovely joke from all the slides.
We have a Matrix channel, MGMT config,
the website, MGMT config.com.
And we don't have a mailing list anymore
because Red Hat used the hostess
and then they nuked the whole infrastructure.
So if you run mailing lists, let me know.
Everyone knows about the technical vlog of James?
Yeah.
I know, it's not that exciting.
If you do want to find out, I'm a purple idea
on all these internet things, on not tomorrow
the day after Monday.
There's this big conference called Config Management Camp,
which is, again, it's free.
It's like a mini-fossed-em, like a thousand people-ish.
And so I give a really technical talk about the tool.
And then on Wednesday, we have a hack day,
which is super fun.
And blah, blah, blah.
Stickers, if you want, that's really all I have.
Thank you so much.
I have maybe one or two minutes for questions.
And then if you want a sticker, come grab,
whoops, come grab outside, I'm happy to give you one.
Question in the back.
Yeah, blah, blah, blah.
So my tool is, yeah, the question is, how does it
compare to this other tool, which I couldn't have heard?
But dox, dox, yeah.
So it's, in some ways, very similar, the same idea, right?
This is more about saying that instead of using one of these tools,
it doesn't necessarily do exactly what you want.
It's so cheap and simple to build exactly what you want
in 700 lines of code, which is like five minutes.
So yeah, great question.
But it's the same rough idea, right?
So yeah.
And one more question, maybe?
Oh, yeah, go ahead.
The score, which is any programming language?
This concept works with every programming language.
My documentation generation tool was designed
for my software.
Of course, it's open source, so you can adapt it.
So really, if you're writing and going,
then you can definitely steal this and probably do
close to what you want.
So a good question.
You had a question somewhere here?
Yeah.
Anyone else?
I hope you enjoyed this.
And do me a big favor.
If you like this talk, go to the organizers,
plug them like one at a time, like DDoS, like,
really like James's talk.
If you look on the website, sometimes there's a voting link
to rate your talk.
So I really appreciate that.
I put all the ratings on my website.
So you can, you know, so we have hopefully
entertaining speakers and stickers outside.
Thank you so much.