Welcome. Our first speaker will be Lorna Jane Mitchell. I always say Lorna Jane in one
word. I think everyone knows me. Yes. But you probably already know Lorna and she's
going to talk about open-source top box. Take it away. Thank you.
Hi everybody. Thanks for coming. It's a busy room and you've had a busy day. I hope your
brains are not too full for something more. My name is Lorna. I'm VP of developer experience
at a company called Redocling. We make API tooling including documentation tooling. I've
worked on docs projects in a couple of previous roles. I describe myself as an engineer with a
writing problem and I'm very happy to be here with some like-minded individuals. I'm also passionate
about open-source. Yeah, my background is in software development. I learned in the open-source
community. I'm an open-source project maintainer, open standards contributor. And I want to bring
to you today how open-source and doc ops works together. So this works better if I plug it in.
There we go. This is the second talk of the day. I'm not sure I'm still got sentences. Okay. What
is doc ops? It's in the talk title. You believed in it enough to be here. Documentation operations
is about allowing documentation to be created, but also maintained and published collaboratively
and in an efficient manner. It's really about being able to make changes and having confidence
and being able to make a lot, a lot, a lot, a lot, a lot of changes with lots of contributors.
And the way I think about doc ops is that it, from some of the more traditional documentation
practices, doc ops is a culture shift. Some of you are enough in the software space to
have seen the DevOps culture shift and we're bringing something very similar to our written
word. Everything I'm going to say in this talk really builds upon the concept of docs
as code. If you are not treating your docs as code, you cannot benefit from the cool
tools that the coders build for themselves that we adopt into our tool chains. This especially
includes source control. Git is the key to many of the workflows that I'm going to talk
about today. Text based markup so that we can manage multiple change sets simultaneously
and bring them together without pain. I personally enjoy rebasing, but you shouldn't have to.
Bringing continuous integration and those practices and also having a good local setup.
If you have to push to see if you did it right, that's not a good documentation creator
experience. And having good tools all the way through the stack is what makes this a
really effective workflow. It makes you very productive and lets the machines do the heavy
lifting. For a long time I used to say the software developers, the coders build the
tools that they want to use, but I don't think they should keep them for themselves.
I think we should take them and bring them into our world of documentation. Open source,
you're at Fosdame, in English I would say I am preaching already to the choir. Open
source means freedom, but it also means not having to build the same tool in every team
that needs to publish a docs platform or check that the links work. It means being able to
run that tool wherever you want to. Tools that fit into continuous integration systems
are typically open source by default. We don't expect it by licenses or sign in, we expect
them just to run on our temporary compute platforms or on our local machines.
Best of all, there's no vendor lock in. So we can choose this tool or that tool and because
we chose that one we're not stuck with having to use another one. We're using standard formats
and open source tools. Just because we didn't have to build and rebuild the tool doesn't
mean we don't have to build it at all. We all need to be participants in the tools that
we use, reporting bugs, fixing things, thanking our maintainers when we see them. It's all
part of the story. So I'd like to share with you some of the tools that I use on my docs
projects and I've tried to pick just a few categories of things that I think are vitally
important. We'll start with the obvious. You need to be able to preview your docs change
before you publish it. Everybody should have access to preview. Everybody who contributes
to the documentation or reviews any docs should have access to a tool like this. This
is a screenshot of VS Code. I'm editing an open API file on this side and this is the
redockly rendering on the right hand side and I typically work like this. So I always
have local tooling that updates immediately. I can see instantly, oh that didn't render
like I expected. There's something wrong with this. I can clearly see that's broken.
My table is missing a cell because I've got that live preview response and this is part
of the story. It doesn't have to be embedded in your IDE. You can run a local server that
updates or use a watch command to rebuild your static site but you should have fast preview
when you are working on documentation. You also need to be able to see the build areas
locally if there are any. I see too many places where that's hidden away somewhere hard. The
other place you need preview is in your pull request. You open the pull request. That needs
to build exactly as it's going to ship. We need to spin up a per pull request preview.
Don't muddle through the branch and put it on a staging server and hope. Pull request
builds for previews and that also enables the reviewers. So it gives them a nice view.
I used to think that previewing docs was for people who weren't technical enough to read
mark down. Now I'm a VP. It's just people who are too busy. You put the web page in front
of me. I can review it. If I have to go past something in a pull request somewhere, it's
a bit less likely to happen. Okay. Link checking. Who has link checking in their docs build
today? Yeah. It's not very many and it's the thing that is most easily rotted in your documentation.
There are two problems. One is all the links between all your own resources which are just
super easy to get wrong. And the other one is other people breaking their links making
you look like a fool. So I use a link checker to check both of those. It automatically does
like a click on all the links. When I'm looking at it for a long time I was building the HTML
and checking the links that after render, which is cool and works. Now I'm working on
more of a dynamic site. I actually have a tool which checks at build time. So I'm using
MLC. There are lots of others. Pick your favorite. So it can read mark down and so then it can
just check. This link makes no sense. Your syntax is terrible. Please do this better.
All those things. Either approach works, but I think it's very important. It's an easy
thing to add. You can run that tool locally. You can run it in CI. The downside of checking
all your links is really other, I mean all the problems are really other people, aren't
they? All the problems are other people. Sometimes the internet goes wrong. I used to work on
a documentation platform which relied on an upstream open source project. Whenever that
project launched a new version, all its links were broken for 12 hours. There comes a point
where you don't want to know what the explanation for that is, but it meant that all of our
builds failed for 12 hours because the links were broken. No, no, their links are broken.
So I have a couple of different strategies for this. One is to only check the links in
the files that are changed because especially on a big documentation set, you don't want
to have to deal with something that's gone wrong in a link from another section might
be owned by another team. So I just do that and then I do a weekly check all the links
job. If that job fails, it opens an issue. So if something's decayed, we'll catch it
maybe not always faster than a customer, but fast enough. So these are some things to think
about. Whether somebody else's broken link or downtime should block your build or your
release because I think that's a other people's links are outside of your control and so that
can be a hazard. Let's talk a bit about validation. If you're coders, you are accustomed to working
with syntax checking tools. Some programming languages will error at build time before you
even run them. Some of them are more interpreted so they don't go wrong until you run them.
We don't historically do that with our documentation, but the tools are there, especially when you
are doing docs as code. So we don't necessarily do that. We don't necessarily do that. We
are doing docs as code. It's got all the advantages of working in code and it's got
all the disadvantages of working in code. It cannot be obvious that something is wrong.
The errors can be super subtle. You have a full stop where the comma should be or the
wrong sort of bracket. This stuff is even when I work with it all the time, can be very
difficult for humans. Super simple for machines. So we can build on those tools and let the
machines do the work. The other thing I like about having the validation errors automated,
I can run them locally. I never do. I always push it and then wonder why it's failed. The
other thing that's nice about that is when you push your pull request and you are missing
a comma or you have the wrong sort of bracket, perhaps this is personal to me, but it feels
kinder coming from a machine than having someone else criticize my use of a bracket.
So that kind of, and I don't have to wait for a person to come and review it. I immediately
get that very impartial factual feedback that my bracket is in fact wrong. And I think that's
what I like about using validation like this. I was going to say the bots are not judging
me. What a horrible thought, are they? The validation tooling, you have a few options
and it depends a bit which flavor of markup you are using. I'm working mostly with markdown
these days, although let's just say it's not because it's my favorite. Let's keep the
markup language war for later. I'm using markdown lint. With markdown I find it very good and
very, very configurable. So like all of the linting tools and the same with open API which
I work with a lot as well, probably some of you have API reference docs, the default settings
for all of those linting tools, the volume is too loud, especially if you were not already
using those linting tools at all. Markdown lint is really configurable and it has really
excellent documentation on what all the options do. It is remarkable how few documentation
tools have a genuinely good documentation. This one does. For restructured text I've
mostly been using that with Sphinx and Sphinx has really great validation and I think it
builds on the docu-tools so you can use that by itself. All of those also come with command
line tools, IDE plugins and you can put them in your continuous integration. So github
actions, Jenkins, whatever it is that you use in your setup, set that up for your pros
content exactly as you do for your code. If you're using open API you should also be
at least validating that. I've already given my open API talk today so I will attempt not
to rant about API linting and standards but put those tools in, set your standard and
make sure that you are consistently checking that. Again it goes in your tooling. Disclaimer
I make, Redock Lease CLI, that's my day job. Other excellent competing open source tools
also exist and I'm probably not the right person to take a recommendation from. I'm
very biased. So we talked about validation, very closely related to validation is formatting.
Again software development does a lot of reformatting of code and that is to give a very consistent
presentation. We always use the same white space in the same way, the same indentation,
the same wrapping rules. It makes it visually very consistent. So when you work with the
same code base all the time it gets easier to read. We can do that for our mark, mark
up, mark down, restructure text, ask, skidock, whatever. We can do that for our tools too.
By allowing things to adjust our new lines, our white space, the indentation, the wrapping,
things like do you need a white, do you need a blank line before your bullet list or after
your heading. Lots of tools don't care when they're rendering but by getting that the
same you can make it easier to read the raw text and easier to look at it and spot problems
because the layout is so consistent. I've only recently started doing this. I write a
lot of docs that are in the same repository as the code and we just turned on the engineers
prettier tool for our mark down. It's actually really nice and I was initially, like of course
you can, I don't mind. Now I'm turning it on everywhere. So yeah, I really recommend
it. I also really enjoy prose linting. Now I don't see enough of this. I'm using a tool
called Veil and I'll be honest, I don't know very many other tools in this space. Lots of
people nodding. Good. I'm also happy to be contradicted like tweet me what I should have
said. With this it comes with, you can give it a dictionary. So it's going to do all of
your spell check for you. It can also do quite a lot of grammar checking. This is brilliant
for me. I work with almost entirely non-native speakers. So having a little bit of help for
me and them to get the words out correctly is brilliant. I am a native speaker, doesn't
always help. So Veil helps me a lot. Also you might be able to tell from my accent, I'm
British. My company is standardised on American English and at this point my spelling can
only be described as mid-Atlantic. So having Veil just to catch those common, we have like
a Britishism's rule enabled and it's because I'm here. Typing all these British spelled
words into our American docs. It catches repeated words. You can teach it product names. In
my previous employment I worked with a company that published a bunch of open source database
products. You have to get people's trademark product names correctly. Up a case, lower
case, trademark. This has to be legally, this has to be correct. So unless you want your
lawyers to have to think about this a lot, you just teach it to Veil. Veil explains it
back to you really regularly. The other thing we did there was we put a bunch of collars
common misspellings in. So we worked on Kafka. When I set up a search for Kaka, loads of
hits. We also banned the English word flick because we had a product called flink. And
indeed we just don't need this word in English because it probably is a misspelled product
name. So those are the sorts of things that Veil can help with. I know we have a Veil
talk next. Yes? A little cheer. So I'm not going to say more about that. Veil's amazing.
Stay and listen to the talk. Okay. Let's talk a little bit then about how all these amazing
different tools that solve different problems and they have your back. They support you
in lots of different ways. But let's talk about how they fit that life cycle, that work
flow. The key is that you are using exactly the same tools with exactly the same config
everywhere between your laptop and your production platform. And that's the goal. Every contributor
needs access to the same tools set up the same way. The tools, if you haven't used them
or you don't yet feel confident because I know lots of people who have been using Git
for years and still think it might bite, which is fair. There are lots of things to learn.
Source control. I'm focused on Git but I've been doing this long enough that I learned
on something else and I don't doubt that there will be more transitions in our future because
that's technology. I like a workflow that's called GitHub flow where you have a main branch,
you make a small change, it gets reviewed, it comes back in. If you see another spelling
mistake, don't put it on this branch. Put it somewhere else. And it means that you can
branch off lots and lots of shoots that are waiting to be reviewed and merged. And in
this way you can multiplex lots of changes and sometimes as a feature it's waiting for
review. Be confident. Actively practice changing branches because it will give you the momentum
to switch a branch, make an edit, push it back. If you are writers, you are probably
editors and reviewers as well, these are the skills that will multiply the stuff you're
already good at by helping, getting the tools to help you. I've talked a bit about the continuous
integration. Always hook everything but you find useful locally, maybe you get an extra
VS Code plug-in. Figure out how to put that into your continuous integration setup and
apply that tool to every pull request. This way we can never forget to check the formatting
or the links because it will just be there. We won't, all that one's a bit risky, I think
we should deploy to staging and check it. The preview will always be there and the machines
will always be on your side. It helps the reviewers to do a better job and it maintains
documentation quality. One of the most important places to have exactly the same tools and
exactly the same config running is on your local machine. The smaller your feedback loop,
the more quickly you can adapt and correct it and move forward. So having to open a pull
request to get the build to see if it's okay, that's a big feedback loop. It's not ideal.
I have one project where I need to do it because we have amazing test harness setup and it's
much faster to run the tests there than here. So I like open the pull request to let the
build build because it's quicker to do that than to wait for it to run locally. But for
most docs tooling, they should be a few seconds at most even on very large doc sites. You must
have them locally. If you use an IDE or similar, you can use a local machine to run the tests
and take the time to figure out how to plug in these tools to that setting. Lots and lots
of them are supported in both places and you can have it in context. I use Vim. All of
those tools are plugged into Vim as well. So it's not modern, hand wavy, cutting edge.
This is stand practice. The other really important thing is that this is all written down. With
documentation specialists, everybody, write down how to set up the tools, how things are
configured, where we publish to, where the sources, how the remote sources come in, how
things are set up, maybe some troubleshooting guides. Write that down. The onboarding should
be easy, whether that's a new hire or you get a new laptop someday. Set yourselves up
for getting it right because again, we're looking for confidence and efficiency and this
sort of thing is part of the culture change. There's a saying in software about move fast
and break things. Dark ops is about move fast and don't break anything. I mean maybe it
doesn't matter as much in documentation because it's easier to iterate than it is in code
or especially in API interfaces. But the goal here is that we have professionals who are
really good at what they do, but the tools can make that faster, easier, simpler, more
accurate. They can catch us on things that we might slip up on. So bring the tools but
also the dark ops mindset into your projects and see where it can take you. I am pretty
much out of time. Here is a list of useful resources. My slides are linked to my session
and I will say thank you for your time.
I think we have maybe like time for two questions.
Would anyone like to ask a question? Yes.
This is a really good question. Do I have tips for helping with the translation of documentation
within the process? I haven't worked on a lot of projects that have this. The ones
that I have, Git is the key because you know which files have changed and which things
have changed. I have mostly seen where the translation is a mirror and whether it's
a week or a month or however often you pay your translation people, you can snapshot
the pages that have changed and get those re-translated. So I think source control helps
a lot with that. One more question.
Could you imagine that you have also very strong opinion regarding documentation and
information or something? I would like to hear it.
I will repeat the question for the stream. The question is do I have a strong opinion
about having documentation in Confluence or Notion or something like that? I have two
strong opinions, not too strong because we are being recorded. The other one maybe we
can talk in the bar. Using a tool like that hurts collaboration because you can't all
make multiple changes at once and bring them back. Like one person is editing, if you were
editing, it's very tricky to do that. The other reason is the lack of standards. So on a very
personal level I have some accessibility needs. If you switch your documentation platform
to Confluence or Notion, I can't do my job anymore. So Doxxus Code is the way because
it lets everyone choose the tools that work.
Thank you.
All right. Thank you very much. I think we have this.