Author: Mick Chesterman
Summary: This blog post contains a proposal to create a new FLOSS Manual on publishing websites, online technical manuals with multiple outputs, and, finally, academic papers and reports. It ends with a link to ways of contributing - see this summary of this proposal as a GitLab issue
I’m writing this in the weeks between submitting my PhD on game coding and the viva exam. While working on the thesis, I developed a workflow for writing and publishing using Markdown as a writing format, with Pandoc and static website tools to create multiple outputs.
At the same time as documenting the process, I began working with Martin Kean on approaches to creating and reviving FLOSS Manuals using a similar toolset as part of a reboot of the project. This post is a first step towards creating a manual to document this process, and an invitation to others who might want to help develop it. To help with this, I will try to communicate some of the technicalities in an accessible way, and also share my own excitement about how it reconnects to some of the earliest processes of publishing HTML on the web.
There is also a wider context to this proposal. In the past, FLOSS Manuals was built around a single, integrated platform that supported writing, editing, and publishing in one place. This was part of its strength and appeal. At the time, more modular or “hybrid” publishing approaches, where different tools are combined into a workflow, did not feel like the right fit for FLOSS Manuals, as we already had Booki and then BookType. These earlier FLOSS Manuals platforms provided an integrated writing and publishing environment, but maintaining this has become increasingly difficult. Thanks are due to SourceFabric and the French FLOSS Manuals community, whose support helped keep these systems running for many years.
So, a more modular, hybrid approach to writing and publishing, rather than maintaining a single system, will allow our focus to shift towards supporting contributors, building partnerships, and enabling different ways of working with shared content.
Some of the communities that FLOSS Manuals served in the past have already moved to this way of working. However, many have not. In particular, the process may be relevant to educators and academics who want to publish in varied formats, for the web and for printing, but who have not adopted writing in Markdown and using static website technology. So I am hoping that this audience may also provide potential co-writers/reviewers of the manual.
What would a manual cover and what are the challenges involved?
Rather than going straight into a full technical guide, it is more useful to sketch out what a manual like this might include. The aim would be to create something practical and modular, where different people could contribute sections based on their own experience. At its core, the manual would describe a writing and publishing approach built around a small set of tools, and how they can be combined to support drafting, revising, and publishing across multiple formats.
This kind of hybrid approach has clear advantages. It allows tools to be swapped out, adapted, and combined in different ways depending on the context. It avoids reliance on a single platform, and makes it easier to maintain and evolve over time.
However, it also introduces challenges. Without a single integrated system, the process can feel fragmented. New users may find it difficult to see how the different tools fit together, or where to begin. One method to counter this confusion is to present a curated set of tools that have been tested to work well together. Later in this post I outline a proposal for those tools. Another way to address this is through a project-based structure. Rather than presenting each tool in isolation, the manual would guide readers through a small number of practical projects, each of which demonstrates how the tools work together in context.
This approach builds on something FLOSS Manuals has done well in the past. Manuals have often been most effective when they support a process, helping readers achieve a concrete outcome, rather than simply documenting features. A project-based structure allows readers to work through the material step by step, building understanding through use.
I would therefore like to structure the manual around two or three main projects that readers would undertake as they read along:
-
Project 1: Create a simple website
An introduction to creating a website using Hugo in a straightforward way, for example by building a simple blog. -
Project 2: Create a FLOSS Manual
Developing a manual using Hugo, focusing on structure, navigation, and publishing, while using simple referencing approaches such as footnotes. -
Project 3: Produce an academic document
Creating an academic paper, book, or dissertation, including the use of references and the tools needed to generate multiple output formats.
Together, these projects would show how a hybrid toolset can support different kinds of writing and publishing, while remaining flexible and reusable.
By working through these projects, a reader would not only learn individual tools, but develop a repeatable approach to writing and publishing. Readers would leave not just with knowledge of specific technologies and how to create or collaborate on a FLOSS Manual, but also with a flexible process that they can adapt to their own contexts.
Suggested toolset and introductory notes
The following tools are introduced as part of the workflows demonstrated in the projects above, rather than as isolated components. The toolset I used comprises Markdown, Hugo, Pandoc, and Git. The following section gives an overview of these components, described in an accessible way. The intention is to show that what these tools offer is of value to a broader audience than just coders.
What is Markdown?
Markdown is a way to write documents in plain text with simple bits of code to indicate formatting, links, references, or images.
The advantage of working in plain text is that it separates content from formatting, reducing layout drift between drafts and making it much easier to restructure large documents.
What is Git?
Git is a version control system that tracks changes to your files over time. It’s commonly used in software development, but it works just as well for writing.
In practice, it means you can:
- go back to earlier versions of your work
- experiment without fear of losing anything
- share and collaborate with others
What is Hugo and static site technology?
Hugo is a static website generator. In simple terms, it takes a collection of Markdown files and turns them into a full website.
The “static” part means that the site is made up of simple files rather than a database-driven system like WordPress. This makes it:
- fast
- easy to host
- more stable over time
For this workflow, it meant I could turn the same source files used for writing into a navigable website, and preview my work easily on different devices.
What is Pandoc?
Pandoc is a command line tool that converts documents between different formats.
In this workflow, it was used to turn Markdown files into:
- Word documents (ODT) for supervisors
- print-ready formats
- structured drafts with references and tables of contents
This meant the same content could be reused across multiple outputs without needing to manually reformat it each time.
What is Zotero?
Zotero is a reference manager, which helps you collect and organise sources such as books, articles, and websites.
It integrates with tools like Pandoc and word processors to automatically insert and format citations. In this workflow, it allowed me to:
- keep track of references in one place
- generate bibliographies automatically
- switch citation styles when needed
It’s useful beyond this workflow as well, especially for academic writing.
Is this workflow for you?
This kind of workflow isn’t for everyone, and it does come with a learning curve. If you are used to more traditional writing tools, some of this may feel unfamiliar at first.
That said, if you are still reading, there is a good chance that the benefits may outweigh the effort of learning it. Here are a few things worth considering:
How are you with the command line? You will need to use the command line for some of this workflow, especially formatting multiple chapters and posts into a book or longer document. You should be prepared to give it a go.
What are your thoughts about Free Software? I am a Free Software advocate and enthusiast. That can help me overcome some frustration when coming up against limitations. I can file a feature request and read about how other users in the community have overcome the same problem. If you share a similar ethos, that probably helps.
How do you feel about using AI to help you? Given some of the technicalities above, using a tool like ChatGPT or a similar AI aid can really help you when you get stuck. It can help surface information from documentation and forums to give you tips. However, it’s not always right and has to be trained and sometimes challenged. If you’re used to that, that will really help.
Some final thoughts
On a personal level, writing in this flexible way is starting to pay off for me now. At this time, I’m writing blog posts to make the material of my PhD chapters more accessible to a non-academic audience. In doing so, I am able to draw on those PhD chapters, the appendices, and even discarded notes to bring into blog posts which are written in the same format. That’s better than trawling through old Word documents and having to wrestle with the formatting errors caused by copying and pasting, not to mention the translation work needed to turn them into web pages on WordPress or LinkedIn and work with the relevant images.
So this gives me greater motivation to turn this workflow into a FLOSS manual that others can use, adapt, and contribute to.
It also reconnects me with an earlier way of working on the web, lightweight, immediate, and hands-on. A process of “patching” things together, working directly with files, and avoiding the complexity of database-driven systems.
If this approach resonates, I would welcome collaborators to help shape the structure, contribute examples, or test the workflow in their own contexts.
I’ve posted a summary of this proposal as a GitLab issue, with some suggested ways for both technical and non-technical contributors to get involved. If you’re interested, please leave a comment there to say how you might like to help.
