Wrapping Up

[00:00:00]
>> If I wanted to serve the documentation site internally instead of on GitHub Pages, and I saw on the documentation and said, Doc, you Saurus.
>> Yep,
>> Burn those markdown files into a documentation site. I'm assuming that's the answer, but they wanted to know a few of them.

[00:00:18]
Any other thoughts? So we made it very clear how you could end up with mark down API documentation. And we got a question in the class about, you know, like if you're not using GitHub, how do you get from mark down files? To something more meaningful, right to maybe a static site, like you put somewhere, put it on an s3 bucket or you know, just serve it up with engine x, something like that.

[00:00:48]
So. I would say like I've tried these dinosaurs and has not been so successful with this. What I have done before is Oops, sorry. I have used let's see, it's not this. It's this, So this is a fantastic little ecosystem. It's a part of this thing called the unified collective.

[00:01:20]
And it sounds kind of like a hippie commune or something. But the idea is they want to have a sts Abstract Syntax trees for things like HTML And text and restructured text, which is what like a lot of the Python community is this, and mark down. So there's this unified collective that sort of at the top level remark is the mark down specific variant of it.

[00:01:50]
And this is super, super, super good at taking in mark down as input and spitting out HTML and there are a slew of, Fantastic little plugins they should surely have a list of them. Here they are. Lots of plugins. What is the red mean? Currently broken, but a lot of green ones.

[00:02:13]
And I actually maintain a couple of these. The green ones you know, like here we go compile markdown to react, help you could drop these. I believe I'm not a Gatsby expert, but I hear Gatsby takes in, like MDX files or something, something that's very, very close to markdown.

[00:02:34]
You could just feed into that. I like that It's your job to take it this last little mile because frankly, for s doc and for for type doc for js doc and why UI doc, all these things they just kind of they're let down in the end right?

[00:02:54]
They don't have good search And I think the world needs some of these. They need a better solution here and markdown is a perfectly acceptable sort of end result. If you don't like that, use the JSON files. There's another thing This. So if you read the API documenter.

[00:03:21]
guides, they mentioned that this Microsoft Project also works with API extractor. And they describe it as like if API if API document or is the go kart. This is the space shuttle. And this is incredibly rich. And frankly, it's a bit complicated because it's designed to work with like any programming language that you might need, right.

[00:03:47]
It's what's used for this site for doc stop Microsoft comm right where you get this nice syntax highlighting the ability to copy things like this. You get It is incredibly rich. It is also very, very, very challenging to set up at this time. So, here's the good news.

[00:04:13]
If you're looking to make an impact in open source, you can figure out how to make this turnkey. It should not be too difficult to do. Maybe not doc effects. But just something that works really well with API Extractor and API Documentor. If you wanna make a Great Gatsby pipeline that's just ready to go and accepts this stuff, I think it could be really, really popular.

[00:04:34]
I think it would take off. That's the short answer. It's an opportunity. With GitHub buying NPM and NPM, involving with seven with workspaces, what do you feel as far as the direction they're going? I'm in opposed to like yarn workspaces, and learn a All right I feel like I should first say I'm a Microsoft employee, which I mean, my Microsoft owns LinkedIn, who I work for.

[00:05:05]
They also and GitHub. GitHub runs NPM. So, I cannot possibly have an unbiased opinion here. I will say, I work with yarn and NPM Had some challenges with it and I have not like, I found that sometimes I would report bugs to NPM and they would be classified as ideas.

[00:05:35]
Right. So I think I have more faith in the management of the yarn project at this time. I think that there's room for two package managers or three or four. I just see yarn as the best thing in, October of 2020. I feel like it is the best thing for my needs in this ecosystem.

[00:05:58]
And I think that that They've provided a good solution in this space that minimises foot gun kind of problems.
>> Yeah, there's another question along the lines of learn on not being super active anymore.
>> All right, so the question we got in the class was Like somebody noticed that learner appears to be short on maintainers at this time in october 2020 and that's a real thing that's happening right now.

[00:06:31]
There's sort of a bottleneck where there are a lot of people are hoping things will get fixed and they have poll requests that are opened and it takes effort to manage these projects and it seems like
>> There's slow advancement at this time. Here's what I think is important to know as a viewer of this course, learner is a tool that we use to carry out a job.

[00:06:56]
And it the only trace it leaves in your project is that config file, learn dot JSON. So don't feel like you're heavily buying into it. An ecosystem where the future's uncertain. It just does some things and other tools in this space like bolt potentially, or the rush stack, which is what Microsoft uses for its TypeScript project.

[00:07:22]
Or, you know, even like yarn workspaces won't become that tool. It has clearly stated that just want to be a low level. API they, like yarn workspaces is where it ends and they're not trying to become the learner in the space. So don't worry too much about being locked in.

[00:07:41]
I don't see it happening that way. I do see that it everything else that is being built right now that's new and shiny. In the mono repo space. It's kind of standing on learners shoulders. Right? So like don't the good things that look like they might be better than learn out there only that way because of what they learned from Lerna But yeah, these things happen.

[00:08:08]
So I don't think that learner will necessarily be around the de facto solution forever. Just because some people have some new ideas and in particular, I think for tools like these people are starting to write them in in rust and just trying to make the CI tools as fast and snappy and responsive as possible.

[00:08:31]
>> That might be the path forward. Just don't don't stress about it too much because you're not locked in. You can always ditch learner and get whatever's next. The concept of a mono repo is more closely linked to the node require resolve algorithm and the idea of workspaces that is going nowhere from what I can see, So any tool that aims to work in that space will continue to work.

[00:08:56]
And you'll just swap one out for the other. So, a question came up in class about version two documentation. This is super important and also why I like to check my markdown docs into GitHub. Because what that lets me do is just sort of roll back, roll forward, etc.

[00:09:16]
Not a whole lot of documentation, hosting sites, support versioning all that well. But what we do at LinkedIn, we have a Think of it like, we have S3 buckets where we can just toss static sites. And we just build the version number into the URL scheme. So when we create a tarball and we publish it and we'll say this is slack slash types.

[00:09:46]
Version, 007, publish. And then we'll have our doc site that users had, where we just iframe the appropriate versions of things into place. So you could like, potentially, you could just run a command in your project, and it'll bake the right versions of things into query puram. And then you can kind of just fetch the right things from the right places.

[00:10:10]
That's a tricky problem thought. I think once, there's a good way to publish this kind of thing, then versioning gets a lot easier. Just to recap what we've done, we started with a pretty empty monorepo or not even a monorepo, right? We started with Yarn and knit, very basic project.

[00:10:33]
We went with yarn workspaces. We added tests linting, we learned about scripting. So you can consolidate your shell scripts, right? Get get that scripting out of your package JSON and into a place where you can manage it. You can work on it like it's code because it is.

[00:10:53]
We use learner. And we, we experienced the difference between yarn workspaces and learner. We know what learner does now. And we know the line between yarn workspaces and learner. And then we talked about extracting your API surface. API documentation. And then probably a new pattern to many of you.

[00:11:17]
building an app based mono repo, where we're not just dealing with, you know, the UI kit, like use case. But we're we're using this as a way for teams to have the benefit of encapsulated libraries. Sort of layer their way up to a more complicated application. I hope this was useful for you.

[00:11:38]
And I hope that you learned some tricks that you'll take back to your teams. Because this is a tricky area of the JavaScript and TypeScript ecosystem. And part of the reason I do this is to make sure that, I learned the hard way and you don't have to So thanks very much for your attention.

[00:11:56]
Have a great rest of the day.