Red Hat helps teach about tech writing

In Brno in Czechia, Red Hat’s large local office has been helping the city’s Masaryk University to teach future technical writers. Whenever someone tries to teach, though, they learn as well. At the Open Source Summit in Prague, a senior member of Red Hat’s documentation team in Brno presented a talk called Diagrams & Dragons: Teaching Technical Writing to University Students the Open Source Way. Red Hat has a large site in Brno, which is the second-largest Czech city and is also the home of the respected Masaryk University. Red Hat’s Brno office has a substantial documentation team — this vulture was part of it for a while. For the last four years, Red Hat has been working with the university’s Faculty of Informatics to teach a course unit in technical writing. Jiří Herrman talked about what the course tutors had learned from the students. For FI MUNI, its course PV177 Technical Writing. Red Hat has a page with some of the materials. “RH has been looking into cultivating technical writers in Brno for a while,” he said, but the launch of the course was “delayed due to the 2020 worldwide global… thingy.” The company particularly wants to work on what he described as “that tricky part of technical writing where you actually have to interact with other humans.” Some of the things that struck this former tech-docs writer the most are covered on pages 7 and 9 from Herrman’s short slide deck [PDF], which discuss what didn’t work. Although the course was aimed at students with some technical knowledge, they found that setting classwork with shell-based tools didn’t work: some of the students had never used the command-line, some came with borrowed laptops without admin-level access, and some came with just phones rather than laptops. Some we found less surprising. Getting students to grade one anothers’ work, much as professional tech writers review one another’s contributions, didn’t work well – partly due to the speed required. In the end, the compromise was to give the students a course in grading each other’s work “without pissing each other off.” It didn’t shock us, but we suspect might leave some training vendors taken aback, that interacting with remote teachers who were presenting online didn’t work well – especially when there were multiple tutors, changing with each class. LLM use You may well have already foreseen the biggest “gotcha” for a course that ran for the first time in 2023. It is, naturally, use of LLM. The students were told that they were not allowed to use LLMs during the course, but naturally enough, they did so anyway. Among the problems that Herrman reported were that giving praise to good work that involved LLM use just encouraged more cheating. However, telling students off for it discouraged them, and that encourages cheating. So the team had to come up with some tactics to try to manage this, which involved teaching the students how to use LLMs instead. They did, however, find some things that did work well. Awarding points, even on a semi-arbitrary basis, with occasional secret prizes, as well dispensing feedback via internet-style memes. A final exercise was to role-play a scenario, “Dungeons & Dragons” style. The quest was “I want to be a tech writer, but how to get there?”. This involved navigating a cross-functional team, creating things like release notes, technical notes, and some real documentation for the process. And as the course materials are open source, the graduates ended up with a permanent FOSS record that they can show to prospective employers. There is a project Github, and you can see some of the student’s archived coursework for 2025 and 2026. The issues around LLM use in tech writing were the primary subject of a “Birds of a Feather” session that Herrman moderated earlier: Technical Writing in the Age of AI. He started by asking how many in the audience were using AI in their tech-writing efforts, getting what he called an “overwhelming majority” who were already on-board. What we found interesting is what people said they didn’t use it for. They find even the best models are poor at writing documentation themselves. They’re also poor at drawing diagrams, and at reading them for review purposes. They’re poor at reviewing docs (“AI is too obsequious and so reviews are overly positive,” and “it doesn’t give good feedback on user focus, or structure.”) However, most of the attendees found uses for it all the same. Examples included “Change management” and “Updating to new code” – in other words, identifying which parts of large products had changed and which therefore needed fresh documentation. Others said they used it for “Documenting decisions from meeting notes,” and in other ways, “Collecting information resources for writing,” and worryingly, to “Summarize notes (from conferences, meetings, etc.) and cluster by themes”. Another use was “Reverse engineering code to figure out intent,” or to “Find existing docs to prevent reinvention or duplication.” Tech writing is a demanding job, and pretty much permanently under-resourced. We can’t and don’t blame anyone for grabbing onto anything that might help. Even so, for us, what stood out from this session was the pretty much unanimous agreement among an audience of tech writers that LLMs were poor at doing the job that tech writers themselves did. Reviewing each others’ docs is a core part of the job: tech writers are used to this, and when they review the bots’ efforts, they find the machinese lacking. That fits our impressions, too. What we found alarming is that, although they find the bots poor at doing what the writers know best, even so, they trusted the bots to be competent in other functions, things the writers don’t look at so closely – for example, finding and selecting where docs need updating. The use for summarization is especially alarming: this is something that studies have demonstrated LLMs are bad at. They shorten, not summarize, and that’s no substitute. We find that worrying, but we regularly hear reports of companies pressing staff to use AI more. This is an all-too-human response: “it can’t do my job, but if I must use it, then this stuff isn’t my jurisdiction, and if it messes up, I can blame someone else.” We just worry at whose desk this buck will eventually stop. ®