Fabrice Flore-Thébault – Senior Technical Writer at RED HAT

Projets Libres

–

Interview with Fabrice Flore-Thébault

Walid : For this new episode, we’re going to talk about a topic that isn’t discussed as frequently as you might think in literature and in podcasts, we’re going to talk about documentation. To do this, I invited us to talk to a friend who works as a Technical Writer at Red Hat and who will explain to us a little bit, tell us about the documentation of his job, a little bit of his past and what it means to write professional documentation for projects and in particular in a company like Red Hat. Afterwards, we can take a little bit of that and generalize, look at what it means to write documentation now. So Fabrice, listen, thank you very much first of all and I hope you’re doing well.

Fabrice : yes, it’s going well. Thank you for having me. It’s very nice to hear you and see you when we’ve not been in the same city for a long time now.

Walid : We met when we were both living in Brussels. We had to go to a trade fair in Paris to realize that we lived two streets apart in Brussels, which was quite funny. First question, could you introduce yourself, Fabrice, and tell us a little about your background?

Fabrice’s career

Fabrice : My name is Fabrice. I’m a Frenchman exiled in Belgium who works for an American company, who has a Belgian daughter and a half-British and half-German wife. I am a European citizen of the world. We’ll say that first. I think that’s the most interesting thing.

I was studying history when I heard about free software and Linux and Wikipedia. And I think it all started at that time, at a time when I said to myself that yes, at university, we are told that knowledge is a common good, but we do a lot of things to put barriers in all this. I don’t know. I slipped into it at that moment. That’s how it happened. How does someone who hadn’t used a computer in their entire life start spending nights trying to install Linux. It took me a month to find the halt command to turn off the computer. So, I started with stuff, like starting a computer, it took half an hour because the little Linux, it had to recheck its disks because I hadn’t shut it down properly. So, I didn’t start with the best cards in my hand, but I learned and I hung in there.

And that’s it, by dint of learning, it ended up becoming a job too. And then, I’ve seen the IT professions evolve very, very strongly since then… I started in 2007, 2008, something like that. My first job was IT Support. Do you remember? IT Crowd ?

Walid : Yes.

Fabrice : That’s pretty much the same. In the job description, you have to know how to lift 15 kilos, because it was at the time of cathode ray screens and large designer screens, they weighed 15 kilos. It was a job that wasn’t just behind a laptop, behind a computer all day, but there was a lot of contact with people, there were things that were physical. Lifting a 4U server… Well the first time, you don’t remove the discs and you hurt yourself. And then, the second time, you remove the discs. Now that everything is in the Cloud, lifting servers, I haven’t done that for at least 10 years. And so, my first job, system administrator, has, I think, pretty much disappeared from the planet, because we’ve automated a lot of things. There are many things that are not done at all the same.

There are many things that used to take time and are now immediate. And I think so, every five years or so, my job has completely changed because what we used to do, we don’t do anymore or we do differently. So there you have it, for 10 years, I was on call. I woke up at 4 a.m. on my wedding day to wake up a stuck waiter, a waiter we had forgotten, who had been there for more than 10 years. Stuff like that. And now, I’m writing docs, so…

Walid : So, you start by doing support. At some point, you start to do adminsys. That’s when I met you, you started working on automation, configuration management, etc. And then, do you have the opportunity to branch out to join Red Hat actually?

Fabrice : Yes, but life is not linear. Let’s say, when I was a sysadmin, I found myself in front of things where it was a bit of a journey, if you will. It’s a bit like installing a computer, installing computers for the devs, it was a little bit of a journey, do this, do that, click click click click click click… The problem is that the first time, I like it. The second time, I don’t like it as much. The third time, it bores me. And the tenth time, I make mistakes because I’m not there at all when I do the thing. So, so I very quickly tried to see how repetitive things, I could avoid doing them. And this was at the time, really at the very beginning of configuration management. It was a very new field. It was super interesting that moment. Because we already had to convince people that it was possible, that we could automate and that just the idea wasn’t completely crazy. Now, when you’re in a world where if you don’t have Kubernetes on your resume, you’re going nowhere. It’s funny because Kubernetes is really just something that automates everything.

Or if you haven’t automated it, it doesn’t work. So, we have a paradigm shift that is huge. I’ve gone from managing people’s workstations and servers that are installed by hand to now, writing documentation for a tool that manages Kubernetes on laptops. So in the end, I write what remains to be documented when you find yourself managing a huge fully automated thing.

For a while, I automated server installations, configurations, etc. And then, the moment comes when Kubernetes arrives and you manage a Kubernetes, you no longer manage it with the same tools, so no longer with an Ansible. So, it’s a moment of questioning. And I wondered at that point whether I would rather stay in operations and manage Kubernetes clusters or explain to people how to do it. That’s when I switched to the doc side, knowing that what helped me a lot was that during all those years. From time to time, on free projects, I helped with doc.

And why did I help to do doc? Because I didn’t know how to write code and I wanted to give back to the community tools that had been useful to me. It’s just a matter of, I don’t know, karma, putting the ball back in the center.

Thanks to this project, I did the things that were taking me a long time, I did it in no time. Thanks to automation projects, it’s true, I was able to do in one half what I’m going to do in a full-time job afterwards. And so, part of the half-time that is freed up, I’m still going to use it a little bit to give something back to the project because I think it’s done. I didn’t mind taking it in my employer’s tone, since before, the job, he asked for a full-time job and that in the end, that part of this time that I spend in my own way by contributing to the community, it seemed normal to me. So, I learned about projects, about GLPI, about Rudder. GLPI is a computer asset management tool that I think your listeners have heard of or will hear who will talk to me.

Walid : Yes, certainly will hear about it.

Fabrice : And Rudder, which is also an automation tool, I think you’ve received them or you’re going to receive them too.

Walid : I hope so. Later too.

Fabrice : For Rudder, it’s my first real job as a Technical Writer for a summer, between two jobs. All of this allowed me to prove to my current employer, Red Hat, that I could be a good writer. And then I got into it and it wasn’t at all as I thought.

What is a Technical Writer?

Walid : What is a Technical Writer? What is meant by Technical Writer?

Fabrice : It took me three or four years to ask myself the question, to ask myself the question again and again each time and to try to understand, because it’s not at all what I thought. For me, computer science is first and foremost Unix tools, manpages, online commands and then documentation on a website with a wiki. It’s basically the reference material, actually. That’s what I used the most. In fact, reference documentation is documentation that is written by developers, that is very, very close to code. The Technical Writers, they’re not really going to touch that one. The developers, they’re going to do it well and we trust them. In any case, at Red Hat, this part is done by the developers and the Technical Writers, in fact, they don’t touch it. At Red Hat, the Technical Writers, they come there to produce documentation for users, which is an artifact of marketing and where stories are told. We want to tell stories, in the end. But it’s not as simple as that. That is to say, we have had manuals, user guides, so there is a whole tradition of manuals that comes from IBM in particular with manuals that are thousands of pages long where everything is described.

So, there is this tradition that is there. Let’s say, there are traditions brought by people who work, I think it’s a bit like everywhere.

Basically, there are two families of Technical Writers.

There is a family that, one would say, is the old-fashioned family. It’s kind of the one I’m part of. It’s a family that is very technical, who are people who know how to write code or not, but in any case who know how to read it, who know how to test complicated things… There is a great affinity for code. In general, these are people who have gone through support before. That’s kind of what I did. The course is you learn the technical subject, you learn how to answer user questions and then afterwards, you learn to formalize all that.

And the other family is people who don’t come from the technical world at all. It’s people, they can write docs for… Their field is language, it’s communication. They can write doc for a nuclear power plant. They can write docs on toothpaste tubes, on tractors, cannons.

Actually, it’s funny because they’re people, they can really change industries pretty easily. These are people who will develop techniques to interview people, to succeed in explaining things that they themselves don’t understand. It’s a bit like … much closer to what interpreters do, who do translation. That is to say, when you do translation, you are not necessarily… and you master the language, you don’t necessarily master all the technical side, all the technique of what you’re dealing with.

There are these two profiles, so a more editorial profile, more from the world of publishing, and a more technical profile. I can’t say for the entire IT industry. I know say a little bit about Red Hat.

And so, as a result, it doesn’t pose the same constraints when you want to document software, because you’re going to have either people who are very autonomous in writing, or people to whom you have to explain a lot of things. Because people whose strong point is language, they will interview people and ask: so, how do you do it, etc.

So the draft is largely done by the developers and then, if the Technical Writer is going to change everything.

Walid : There’s one thing you seem to be a little bit silent about, it’s that you’re not just technical, it’s that you come from… Well before, you went to university, you studied where you had to write in really good French or English, in short, I don’t know. That is to say, having worked with you, I am not capable. First of all, I had more trouble putting myself in the user’s shoes than you and two, I’m not able to write… It was more complicated for me, for example, to write in French, good French like you, and to popularize and tell what you call the beautiful story, which was my second question: what is a beautiful story?

Fabrice : Yes, I also did, it’s true, I studied History, but Literature at the same time. The technical doc is a very poor literary genre in fact. We try to transform natural language, in my case, it’s more English, we try to channel a natural language that is Rabelaisian. Each person has his or her own language tics. An American, a Canadian, an Englishman, a Briton, etc. It’s their native language, English, but they’re not going to speak the same. A technical writer, he makes that disappear, he will erase all that. The goal is that the documentation can be read by just about anyone in the world, especially people whose mother tongue is not English at all. We have the poorest possible vocabulary, we have the poorest possible sentence structures and also, we try to keep a content structure that is always as predictable as possible, as simple as possible, as sausage as possible. In fact, we try to talk to the eye and directly to the brain even before people read the words. That is to say, here, I’m just looking at the same time, I’m looking at the file that you prepared, that’s exactly it, it’s checklists.

At Red Hat, for example, we have three types of content and no more. We have a procedure that is the type of content that we use as much as possible, whose structure is defined and from which we do not deviate. And a procedure is: there’s an intro of one or two sentences that basically explains to people why they want to read this procedure. Why do it? That’s why. Then there’s a little subtitle that says: prerequisites. And we list a bullet point list of all the prerequisites before, all the things you have to have done before. Then a procedure which is a numbered list of all the steps to do to do something. And then another checklist and then a bullet list of additional resources that we can check out next. There you go. And so, suddenly, it’s the same all the time. It’s the same all the time. So, a user, he knows that he is already going to have this information. So, there’s this thing. It’s horribly poor, but we’re not here to create. It’s exactly the opposite of literary creation, for example.

So, we have a type that is like that, a type of content that is reference documentation, but that, I don’t know, on a project, there will be reference documentation and 25 procedures and concepts that are the same, which are a chapter. We explain the three concepts on the project and that’s it. There are just the concepts and references that are a little freer in form, but that’s the bulk of the thing. When you take a procedure that is written by…, a draft, which is written by a developer, for example, there is a good chance that there is not a single line left of what was there at the beginning. Because we put it all in a logical order so that information doesn’t arrive along the way. So that’s very important. The prerequisites, we balance them into prerequisites. The sentences are simplified. It’s subject, verb, complement, period. The goal is to use as few words as possible to tell something that everyone will understand without a shadow of a doubt, without in a place where two people will interpret it in a different way.

It’s funny to be able to say to yourself: I’m going to remove 500 words from this text or stuff like that, or how to reduce the number of steps in the procedure from 15 to 7. That’s it, when you use little tricks.

Upstream and downstream concepts

Walid : Could you explain, for listeners who don’t know, what is upstream, which is a word that we hear a lot in free software, and downstream, which is a word that I had heard quite little, except potentially at Red Hat. Can you explain these two words in a simple way, so that then, behind and after, we can start talking about collaboration?

Fabrice : Okay, that’s a rather peculiar way, it’s Red Hat’s business model . The way Red Hat works is to work with projects that are upstream, that is to say projects that are open source projects and that we will find, I think, on GitHub, essentially, GitLab, very little. It’s funny because for us, GitLab is more about downstream repositories, so repositories for products that are in the VPN and therefore to which people outside the company don’t have access. So, we’re going to, from an upstream project, we’re going to make a downstream product. And the downstream, it’s just created from upstream.

It’s just the metaphor of the source. Open source, a source comes from the source. So upstream, it comes from when it’s a stream. And downstream, if you go down and you’ll find the river again.

Walid : On the projects you work on, you always have an upstream which is the open source project and a downstream which is the Red Hat commercial product.

Fabrice : exception: the project where for the moment, we don’t have a downstream. Generally speaking, yes, Red Hat participates in projects and then they will build a product where the added value of Red Hat is the security audit, it is to make the mess run in the context of a large company, that is to say to integrate with backups, to integrate with centralized authentications, to integrate with really all the mess that there is in a large company to run something. It’s not enough to make an application that makes little Mickeys. To access the little Mickeys, you need to be able to authenticate yourself with the SSO of the box. And then, the little Mickeys, we have to be able to “backup” them with the backup tool of the company. The project, on the other hand, focuses on functionality. I show little Mickeys. The “productization” part takes care of everything else. So everything related to security, management of security patches, etc. All the delivery to the customer is also packaged and easier to install. It has an impact on the projects every time. It’s that a project that goes its own way just to make features, when it has to be “productized”, transformed into a product, it slows down the development a lot because you have to check that this and that, it’s compatible.

I’m working on a project right now called Podman Desktop. We’re trying to go very, very fast and we don’t have any product. It’s entirely communal. It’s quite rare, but not completely rare at Red Hat, because if you think about it, Ansible is the automation tool that killed all other automation tools. Red Hat took a long time to figure out how to turn this into a product.

Walid : Can you name one or two references upstream versus downstream in the context of Red Hat?

Fabrice : The Fedora Linux distribution is the upstream of the Red Hat Enterprise Linux distribution. For people who are in the Linux world, this is perhaps the most obvious. It has become even more complex since CentOS… CentOS was a downstream of Red Hat: they took the Red Hat distribution and repackaged it freely. That is to say, it was upstream, downstream and it went back to upstream. Red Hat has turned that the same way as the rest. That is to say, now, CentOS is more of an upstream than a downstream.

Kubernetes is the upstream for OpenShift. What does Red Hat do? On top of that, Kubernetes is added to everything that is security and everything that is necessary to make Kubernetes work in the business world. Which means that in general, a container that will run on Docker, on Podman, on a container engine, which will then run on Kubernetes, will wallow on OpenShift. The security requirements for running things on OpenShift raise the bar pretty high.

Documentation Formats and Tools

Walid : When you’re a Technical Writer, how do you fit into projects? What is your relationship with developers, marketing people? What is your relationship with the communities?

Fabrice : It depends a lot on how you organize the flow of documentation. That is, do we put a team of upstream writers and a team of downstream writers ? And then, in fact, the soup is not passed around. This is a bit like what happens between Fedora and RHEL. It’s very much the case to have things where the passage of the two is not done. Or you choose to do the documentation in the upstream project, so it’s visible from GitHub. You go to GitHub, you see the documentation on GitHub, you have the complete documentation. That’s Ansible, AWX. There are a lot of projects like that. But it’s not the rule at Red Hat, it’s more complicated technically. You need to have the pipeline that allows you to transform your upstream documentation with the name of the project, for example, into a documentation in downstream where it’s no longer the name of the project, it’s the name of the product. You have to have solid stuff to do that. We do good things, there are projects that do good things. We’re lucky, it’s a great project called Antora. Antora which is a content management and documentation tool made in AsciiDoc.

There’s AsciiDoc, the language, which is a markup language comparable to Markdown or reStructuredText, just the spec of the language. Then we have Asciidoctor, the implementation in several languages of something that has been transformed, this markup, into something else: HTML, PDF, epub, slides. And then, Antora, which is a project that makes it possible to make a real doc site. That is to say, to make a real doc site with a navigation. So, it’s going to manage navigation, it’s going to manage links, it’s going to manage versions, it’s going to manage the fact that we’re going to look for bits of docs in code where the content is written in different places, but we want to publish them all in the same place. It’s a magnificent tool. For me, it’s very comparable to Ansible to making playbooks because you put together stuff that comes from everywhere. We manage to have fairly complex pipelines that do great things. That is to say, in five minutes the content is “merged” on the upstream project, it is published directly on the upstream documentation, let’s say, every night or even at the time of the how, the content arrives in the product. You can be a tech writer and do automation.

Walid : Not too long ago, you gave a conference at FOSDEM on the subject. I’ll put the link in any case in the comments. If I understand correctly, you take your knowledge of configuration management and automation and you applied it to the doc.

Fabrice : For the moment, I help my colleagues a lot. There are people who want to do the same, in any case. This is an example, it is not the only project where this happens. What may have been different on my projects is that it was the Technical Writer who did the job and it was not the devs. There are expansions for Antora that arrived a year ago. We started using them when they weren’t out of the oven. We used really new things. Dan Allen, Antora’s guru, also works for companies that have big docs and big needs. He managed to do something pretty great, which is that he has a job as a software developer, documentation, he does everything. He developed the specs, he developed the basic interpreter, he developed all the tools around it. It’s just impressive to see him working, to see him also manage the community because he is very present to respond to the community of users. This guy is a beast, it’s incredible. And when you compare it to the mess that it’s on the Markdown side, there’s no comparison.

The Markdown naked with nothing else, we don’t do much. All the people who use Markdown, they add extensions per folder, this, that. There are endless Markdown flavors . For the moment, it’s refocusing on something called MDX (Extended Markdown), which, basically, we’re trying to take what we’ve been doing for a long time and put it in Markdown. My current project is Markdown and I’m not a big fan, but the developers love it.

Who writes the doc and with what constraints?

Walid : There, your background in automation has a direct influence on your ability to automate the document. That’s quite interesting, but for those who want to know more, I think the FODSEM conference explains it very well. There is one thing, when we were preparing, that interested me a lot, and that was the evolution of documentation. What you were telling me when we started was that the documentation, at the very beginning of free projects, was done by the developers, because the developers, basically, were people who came out of big universities, etc. They had the level.

Fabrice : And their users too. It’s always worth drawing parallels with other inventions like that. For example, reading. We take reading back to the Middle Ages. Reading in the Middle Ages, there are very few people who know how to read, there are very few people who know how to write. Everything that is written is basically written for people who have the same level of education as the person who writes. It gives complex things. We don’t have Scrooge Magazine, we don’t have that kind of stuff. It’s something that we’re going to find in iconography, that we’re going to find in painting, in other things, but that we’re not going to find in writing. IT is the same. We started to have people who were all with huge universities, who have a university career of at least 10 years before taking care of computer science. So, they are people, they have vocabulary, they have a very strong ability to enunciate and to state complex things. But they also speak to people who have vocabulary and who have the ability to understand things, complex things.

We want any software to be usable by someone who took their first English course the previous month and has a vocabulary of 150 words.

The same goes for developers. A developer now is someone who has done much more specialized studies than a developer of the seventies. A developer of the seventies, he read Kant. There’s no problem with that, I think. A developer of the 2020s, there are some who can, but there are some who can’t. It’s not saying something mean to say that, but it’s just that we’re not at the same level of education. We are not at all in the same literary genre, let’s say. So, there is that. And then, there is also the fact that we have moved from documentation that is essentially reference documentation, that is to say: “But what does it do? How can I do that? And I’m going to read something, I’m going to look at all the options, etc., and I’m going to find mine,” to something where it’s more marketing that’s there. That is to say, I think that the doc, now, is a marketing tool where someone who doesn’t know the product has to see stories, has to see how to use the product, why do it. We tell stories and the stories will bring features to the application.

What we are trying not to do at all is to have a copy of the application. We’re not describing the application. We are there to get people to use the tool. We are not describing the tool, we are explaining why to use it, how to use it and what to strive for.

Walid : If we go back to the beginning of free software, the developers were able to write the manpages, which is generally still the case, and they were able to write all the doc which was technical in addition, and they were the ones who did everything. But now, basically, the developer, he always writes the reference doc, which can be a manpage or something else. And besides that, there is a whole population of other people who will do the additional docs. You, the Technical Writer, will write the use cases, the story, etc. And then, there is, also because of the evolution of the Internet and the evolution of uses, you also have a whole set of other resources that you have at your disposal, that you didn’t necessarily have at your disposal on the side, which will also allow you to learn and on which you, I think, don’t work too much. I’m thinking, for example, of tutorials and videos. Me, for example, in no-code, a lot of LinkedIn posts, Twitch live, etc. So, it’s still different populations that don’t necessarily coexist with what you do.

Fabrice : I also wanted to talk about a tradition among Technical Writers, which is the manual of style, the style guide. It’s something that’s super important. So the Chicago Manual of Style, it’s from the ’20s, I think, something like that. There was a style manual which is a kind of Bible that explains how you write documentation. It doesn’t matter why. It’s how you write factual content that describes something, etc. It defines how you use commas. This explains why we shouldn’t use the passive voice because the passive voice has introduced uncertainty, etc. This is the basic pact of the Technical Writer. This is the Technical Writer’s Bible. This is what makes it difficult for Technical Writers who do docs to switch to another medium, to make videos or slides or to give courses, etc. It’s because of this manual of style which is something that is very formative.

When I started at Red Hat, I felt like my role was really language policing. I was expecting to have a role as an explorer and creator, but no, most of the work is boring. It’s just: “No, you have a passive voice, you have to remove”, “No, don’t do commas like that”, “No, in the titles, we don’t put capitals or stuff like that”. I don’t know much about publishing, literary publishing. well publishing, people who make books, but I think there are also layers like that of jobs between the publisher who changes the structure of an entire book and the proofreader who will find the typos and missing commas and stuff like that. And so, I think that in the work of Technical Writer, we have a single title, but there are all these roles that are also found. We are in the world of publishing, but structured a little differently. Publishing books, the job of making books and making guides and writing, it’s not the same job as the job of doing radio, recording blogs or making films. Basically, it’s not the same job at all. It doesn’t require mastery of the same thing. It doesn’t require mastery of written and oral language, it’s not the same codes.

I know that this exercise, for example, of participating in a blog, for me, is an entirely different thing from my daily life.

Walid : Basically, I’m drawing a parallel with… A few years ago, we set up a company with other people, we made roller skates, everything related to communication and marketing, all that was integrated. That is to say that you couldn’t communicate on one medium if you didn’t communicate on another and understand what you were going to release, when and how you were going to talk about your product on this medium versus that media, it wasn’t the same thing, etc. So my question was also to know: do you have a role in all this? And potentially, there may be other people in marketing who have a different role and know were you, you in contact and there was some coordination?

Fabrice : let’s say, there are docs, it would be nice if they were ready for releases, for example, stuff like that. We are like encyclopaedists in front of journalists. The content we offer is much closer to encyclopedia content and much less close to journalist or blogger content. The blogger, he’s in the event. He’s in the “I’m delivering something here and now”. Here and now: message. Whereas when you do doc, you try to do something that will survive time. That is, I’m going to try a blog, I’m going to put a screenshot with today’s version and now I’m going to make a video with what’s in the app today and now. You don’t do that in docs because you’re going to do the exact opposite. You’re going to do as few screenshots as possible, because it’s too much maintenance and it’s too much of a waste of time. If there is the product version in it, you have to update with each version. And so, the screenshots, if there is a revamp of the user interface, it’s all over again. So, we have objectives that are very, very, very different.

Now, I recently made a blog post for the project. It came out a bit like a doc that is put in a blog. I’m not very proud of myself, but I realized that it was a very different exercise. It was very difficult for me to go from the very cold doc to something a little more convivial. And since I’m used to writing docs, we remove the words, which is very skeletal. It was to put a little bit of a link back in there. That was the challenge of the thing. I’m not too sure if I’ve arrived, but here it is.

“Productization” of free software

Walid : How many Technical Writers are there at Red Hat, for example?

Fabrice : I think there were more than a hundred. I don’t know if it’s just a prediction or in general. It’s not huge either. We’re at a ratio of 1 to 15 developers roughly, I’d say, something like that, 1 to 10, 1 to 15. Now, I’m on a project where there are less than 15 developers and I’m a writer in it, it’s quite exceptional. The project I was in before, for the moment, there are three. There were three of us at a time when there were 40 developers.

Walid : What is the impact of putting Technical Writers on the project? Does it speed up the project? Does this slow down the project?

Fabrice : In general, we use Technical Writers when we do “productization”, i.e. when we brake. “Productization” slows down the project, inevitably. That’s where we’re going to put QAs, so people who do quality, testing. We’re going to put testers, we’re going to put in doc. I’m not saying that it’s the writers who slow down the project, but the writers, in general, are very much linked to “productized” stuff that goes slowly. For me, who came more from a world of service companies where we deliver quickly and we will do a review and then another review. For me, it can take time because we’re going to have a review where it’s the developers who will say: yes, technically, it works. Then afterwards, we’ll have a review where other writers will say: yes but you didn’t follow the guide style. So yes, it’s longer, but it’s not necessarily the case. I’m trying to keep up with a purely community project, there are half a dozen of them and the stuff goes by super fast. So if I take a screenshot on Monday, Friday, it’s more like that.

And people think it’s easy and fast to write docs. And this is not the case. It’s not easy and it doesn’t go fast.

That is to say, when you write a procedure, first, you have to find the logical flow and get to do the thing that is in it. That already takes a while. Then, you have to check that there is no one who will misunderstand the thing and who will do something else. There is all that. There is something to be made conform to the language afterwards, but it is not the most complex. We have tools now for that. We have like code linters, but linters for the doc, so who say: no passive voice you don’t have the right. This kind of thing, you have to test, then afterwards, you have to validate. And then, when it’s something that goes from upstream to downstream, you also have to make sure that it goes downstream. In particular, that we don’t introduce examples that we absolutely can’t put downstream or stuff like that.

Walid : Two questions on that. What tools do you use? And the second is: you said earlier that you were able to test. You say that writing docs takes time. Does it also take time because you’re going to install the tool and you’re going to test it functionally?

Fabrice : Testing the thing is almost what takes the most time. I try not to waste developers’ time. So, I try to figure things out on my own, and I tend to fart stuff a lot as well. What’s also slow is that the people who write the docs are the first users for the developers. Developers, they’re focused on a feature and just the feature they’re doing. But they are not users of the finished product, very few. A while ago, I had discussed with people who make a fork of PostgreSQL, so database software. And I was talking to them as a former database operator, like the things you have to think about when you make databases. So someone, a developer who has been writing code to make the database for 20 years, 25 years. And at one point, the conversation was cut short because he told me: No, but I’ve never been the operator of a large database server. I don’t know what you’re talking about.

So, writers are the first users. In general, when we use, it’s to document a feature that is new. Usually, we document a feature that’s a little bit not very mature, so we see the things that hurt. We do: yes, but look in such and such a case it doesn’t work, etc. There is also a whole part. In any case, that’s how I do my job. There’s a whole part that is to report information about things that aren’t right. After that, do I open tickets on GitHub or do I send stuff to instant messaging? What is going best? It depends on the relationship with the team, with the developers, etc. I am in favour of the Agile Manifesto, early 2000 version: “Individuals and Interactions before Processes and Tools“. So, work is first and foremost about people, it’s first and foremost about interactions. Then, we put processes and tools in place, but it’s not the processes and tools that are important. I think that’s really important for someone who does automation, also to know that it’s not the tools that are important, it’s the people.

Walid : Precisely, you’re talking about tools. What tools do you use? Now, you’re talking about GitHub.

Fabrice : The important thing is that it’s documentation for software. Documentation is for software. We try to make it as close as possible to the developers’ code. Afterwards, there are debates, there are people who say: we need a separate repository , etc. But anyway, it’s going to be… If developers write code, it’s in Git repositories , the documentation will be in Git repositories too. There is no discussion about that. So, putting in the same repository or a repository next to it, in the end, it’s not a big variation. But it’s in a Git repository . There are quite a few different markup languages that one can choose from. So, starting from the older ones, but staying in the open source world, there’s LaTeX, but I don’t think many people are going to write LaTeX now. LaTeX was rather dethroned by XML in the 2000s. And for the documentation, we have something called DocBook, which is XML to make doc. At one point, the developers at Red Hat, they still said, at a certain point: no, DocBook, it stinks, we don’t want to contribute. We have to find something else so that we can contribute to the document.

So, we said: okay, we’re going to do something else. And that’s how AsciiDoc came about. You could do Markdown, reStrcturedText or AsciiDoc. At that time, AsciiDoc had a converter that could translate from AsciiDoc to DocBook. The whole Red Hat build chain was based on the DocBook. So, for now, we’re still in that legacy, since we have AsciiDoc that’s been transformed into a DocBook and that goes into the old pipeline that was really created by Red Hat. The libXML was created by Daniel Veillard who is now… I work with him, I’m too proud.

Walid : Apart from the language used to make the documentary, what tools do you collaborate with?

Fabrice : First of all, Git, GitHub, GitLab. At Red Hat, the projects are on GitHub and the products are on GitLab. We have two different Git platforms. Github, there are all tools for use that are on actions, pages, etc. This is used quite extensively. GitLab too, everything that is automation, containers, and GitHub and GitLab know how to use containers, go “pull” a container and do stuff in the container that is “pulled”. That’s a technology that we use a little bit all the time. As a result, people each use their favorite IDE, their favorite editor, if you will. Visual Studio Code is very present. In fact, we used Atom a lot and then Atom was abandoned by Microsoft in favor of VS Code. A large minority who are on the IntelliJ Community. I use a lot because the extension for AsciiDoc is just wonderful, it’s just too good. There are people who say Vim, Emacs, Kate, other stuff.

Walid : For everything that has to do with cats, for example?

Fabrice : I think that now, the official platform is Slack. For a long time, there was Slack, Google Chat, IRC in parallel and more after projects that have other tools, like Mattermost, Discord. My project is both on Discord and on Matrix IRC. I stopped using Discord after two weeks, I couldn’t take the advertising messages in it anymore. Projects bring their own thing. When the project, in addition, is overseen by one foundation or another, the foundation brings its tools, these recommendations, these tricks. And then, there are things that you can use or not depending on. Like the Eclipse Foundation, they’re on GitLab, they refuse to use JIRA, for example. So, we can’t put a project at JIRA if it’s for the Eclipse Foundation, so it has to stay on something else. You see? Yes, JIRA. For everything that is produced, it is JIRA. For anything upstream, often, it’s very, very sufficient GitHub.

Document no-code

Walid : This brings me to the last part that I wanted to address, that we talked about a little before and that I thought about a lot, since that’s the field I’m in now, which is the whole no-code, low-code part. So you, you do what is called doc-as-code. And the problem is how do you do doc when there is no more code? It’s a pretty interesting field, especially when, like me, you come from development and you arrive in tools in which you don’t develop anymore or quite little. How do you do that? When we were talking, you told me: yes, but in fact, how does it work? With the tools for the general public and the tools that are used in general, for example, we have a French no-code community where there are about 10,000 people, something like that. And finally, even people who do a lot of no-code, there are still a large part of them who don’t do docs. However, as I say every time, when you are an IT professional, you have to write docs.

And so, you have tools that have become established over time to overcome this. You have certain tools, I’m thinking of automation tools, for example, which allow you to document in your automation workflows, you document parts, you basically do what you used to do in code with it. And you have tools like some front tools, for example, where there’s nothing. So, you have to document in another way. And so, you have a whole ecosystem that has been built around it. There, for example, you were talking about JIRA. It’s interesting because in the no-code and startup world that I’m more involved in, the basic tool for documenting is Notion, which is basically a tool that can do everything. It makes you databases, it makes your knowledge base, it makes your ticketing, it does everything to you. Everything I was doing before with ticketing tools, you do it in Notion, so less well and certainly less optimized, but you can link everything, it’s impressive. It’s another way of doing things. You have in front of you a tool where you can write docs, it becomes a process, once you understand how it works super simple and you can hyper structure, you have lots of templates and everything, it’s really quite interesting.

And besides that, all the stuff that you can’t document, that you could do in code on everything related to dependency management, regression testing, that kind of thing, with no-code, either you don’t do it, or you have new tools that are created. And there’s one tool in particular, for example, that I use a lot and that I’m pretty close to the development team with called ncScale. It’s French people who do this and it’s a tool that allows me to do a little bit of what I used to do with my ITSM tools, which is automated inventory, dependency management, this kind of thing around no-code tools, it’s really interesting, and documentation. And so in fact these new forms of documentation where in the end, you no longer have code, so you can no longer document in code like you, you are used to doing.

Fabrice : Notion, it’s a bit like a wiki, isn’t it?

Walid : Notion is both a wiki and a database. Unfortunately, it is not a free tool, and whose user interface is really extremely well thought out and extremely logical, which allows you to link everything. To tell other people, they told me: basically, it’s just JIRA with a great interface.

Fabrice : JIRA or Confluence?

Walid : Confluence, sorry.

Fabrice : For example, if it’s like Confluence, what’s missing in Confluence is that there is no process for validating the change. I think the most important thing we use Git for is the review. This is the pull request, the review and therefore the validation of the change. That is to say, you want to change something and there will be five people who will read the change and say: OK, it’s okay. There’s this idea that it’s not: you change, you publish and then afterwards, if it’s not good, we change. It’s: you propose a change, we check and once it’s accepted, we’re sure that everything is fine. I’ve used Confluence a lot for internal procedures on documentation that doesn’t need validation, that doesn’t need to go through a validation workflow. And so, for that, a tool, a wiki, Confluence, whatever, Drupal, any system that allows you to write something and publish it, everything is good. There are people’s preferences. There is what works better, what is closest to the rest of what you do, but everything is good.

What makes the difference is when you want to introduce a validation process.

For release notes, we started to introduce the fact that in each JIRA issue, we have a field that is with the content of the release notes. It worked well as long as writing the content and validating it was done in one go by the same person. I read what’s in the ticket, where often, it was tickets that were copied by the way. Ok, there you go. And I write and I make my sentence and it’s done. And I don’t think about it for five minutes. We then passed it on to users who were more junior and as a result, there was a need for validation. It became a gas plant because we had to add a field to say: draft, it’s a review, it’s validated, it’s OK. But on the other hand, we use a JIRA field which is a field that has no history. So, we can look at the logs of the changes, but it’s not something that’s made for that.

Walid : I’m not the biggest specialist in Notion, but I’m not sure you have that kind of validation workflow notion.

Fabrice : The internal documentation and the documentation of the product you built for users are two different things. I think that Technical Writers, typically, are more there to go and do your documentation in front of the client. Internal documentation, you need to introduce validation processes at a time when the team is growing. Above all, the degrees of seniority are changing. The person who is more junior, he has to be able to change things and know that there is someone who will see him back and that allows him to get started. I found an app that I really like, which is called Obsidian. Obsidian is that, it’s a knowledge base. It’s done in Markdown with the two or three Markdown extensions that allow you to make links and include between files. So it’s perfect, it’s great. One of the extensions is to be able to put the content in Git. It allows two things. The first thing is that it allows you to have a history, that is to say to see what happened before. And the second thing, it allows you to have the same content on your phone and on your computer and to pass the content from one to the other without going through a platform or another thing.

It’s a Git repository . It introduces the notion of history, not really the notion of validation, but the notion of history in the doc and you can see when it has changed. I know that I am using more and more as a measure of personal hygiene. What have I been doing these days?

Impact of Artificial Intelligence

Walid : Before we hang up the microphone, a subject that I can’t not talk about is the arrival of artificial intelligence and the impact it will have on some of the publications and your work. Do you already have ideas or do you already see things that were previously made by humans and are now being done by artificial intelligence?

Fabrice : I find it fascinating. I think that what will happen, it is difficult to measure. I’ve seen people who had fun making punchlines for marketing campaigns that asked an AI to generate the punchlines for them and it worked really well. That’s one of the characteristics of this thing, is that you can say to him: look, I’ve made a rotten sheet, can you make me compatible with the Bible of how we write? And if you’ve trained your model well, it’s going to do it. When you’re writing docs in uncharted waters, when you’re on something brand new where artificial intelligence, it doesn’t have much to sink its teeth into, it’s a parrot it needs existing content, so, when you’re writing about something that’s fundamentally new, artificial intelligence, at least for the moment, She doesn’t have much to find. I try to tell myself that at night so that I can fall asleep. Otherwise, I see how, for example, the Ansible project was used on a project called LightSpeed. It’s not documenting the code, it’s writing the code from the documentation.

That is to say, I want to do a task that does this, so we write it in natural language: install a server for me, install this package for me and the tool will write the code of the Ansible playbook for the user. So for now, we’re writing the natural language and it’s going to write the code. We have this part that is being put in place and that still requires human control. It’s just a template that makes the work easier. The job of Tech Writers, which is the opposite, is from code, describe what you want. At that point, the AI needs to have a ticket or a brief for the code that is super well done. That’s right? This is rarely the case. Or a way to go and find out as well as a human being why I want to do this and how I’m going to do it, because that’s it, you have to find both things. For the moment, I don’t know. I thought a few years ago that when we had everything automated, we would still have to document the automation and that it was a good idea to go and do some documentation.

Walid : You can already ask ChatGPT to write you the text of your pull requests.

Fabrice : If the Technical Writer, his role, is just to do that, it’s not a job of the future. Above all, I think it will change the way people consume doc. It doesn’t really make sense to say: I’m going to continue writing documentation if people aren’t going to read documentation anymore. If people, they’re going to ask questions to another. The writers‘ job will be to produce content that artificial intelligence will ingest and that will be useful to artificial intelligence. I think that for it to work well, it has to be content that is even more formatted, that has even more metadata. Because I think that raw content is not very useful. For the moment, there are still people who add metadata to content. Maybe it’s going to move that way, people who are more language-bound, they’re going to move more towards producing raw content to feed the machine. But I don’t know what will happen. Where we’re going, I don’t really know.

Op-Ed

Walid : Finally, I have a traditional op-ed. So it’s up to you.

Fabrice : Free software, people, it’s good! Contribute to free software. I don’t know if I’m really an old idiot to say that or what. I have the impression that the expectations for the younger generations are no longer the same. I don’t know if Linux will end up being more than for servers and not at all elsewhere, for example. I ask myself this question. I ask myself: what will the new revolution be in five years? Because in any case, everything changes every five years. It’s still interesting this world where everything changes very quickly.

Walid : That’s the last word. Thank you Fabrice for taking the time to talk about these subjects around documentation. I think that if you liked it, of course, don’t hesitate to share it on social networks and talk about it around you. See you again.

This episode was recorded on May 3, 2023.

Transcription by Raphaël Semeteys

Learn more

License

This podcast is published under the double license Art Libre 1.3 or later – CC BY-SA 2.0 or later.

, , , ,