Title: Story of making the OpenBSD Webzine | |
Author: Solène | |
Date: 01 October 2021 | |
Tags: openbsd webzine | |
Description: | |
# Introduction | |
Hello readers! I just started a Webzine dedicated to the OpenBSD | |
project and community. I'd like to tell you the process of its | |
creation. | |
The OpenBSD Webzine | |
# Idea | |
A week ago I joked on an french OpenBSD IRC channel that it would be | |
nice to do a webzine to gather some quotes and links about OpenBSD, I | |
didn't thought it would be real a few days later. OpenBSD has a small | |
community and even if we can get some news from Mastodon, Twitter, | |
watching new commits, writing blog articles about stuff, we had nothing | |
gathering all of that. I can't imagine most OpenBSD users being able | |
or willing to follow everything happening in the project, so I thought | |
a Webzine targeting average OpenBSD users would be fine. The ultimate | |
accomplishment would be that when we release a new Webzine issue, | |
readers would enjoy reading it with a nice cup of their favorite drink, | |
like if it was one's favorite hobby 'zine. | |
# Technology doesn't matter | |
At first I wanted the Webzine to look like a news paper, so I tried to | |
use Scribus (used to make magazines and serious stuff) and make a | |
mockup to see what it would look like. Then I shared it with a small | |
French community and some people suggested I should use LaTeX for the | |
job, I replied it was not great for handling the layout exactly as I | |
wanted but I challenged that person to show me something done with | |
LaTeX that looks better than my Scribus mockup. | |
One hour later, that person came with a PDF generated from LaTeX with | |
the same content, and it looked very great! I like LaTeX but I | |
couldn't believe it could be used efficiently for this job. I | |
immediately made changes to my Scribus version to improve it, taking | |
the LaTeX PDF version as a model and I released a new version. At that | |
time, I had two PDF generated from two different tools. | |
A few people suggested me to make a version using mdoc, I joked because | |
it wasn't serious, but because boredom is a powerful driving force I | |
decided to reuse the content of my mockup to do another mockup with | |
mdoc. I chose to export it to html and had to write a simple CSS style | |
sheet to make it look nice, but ultimately mdoc export had some issues | |
and required to apply changes with sed to the output to fix the HTML | |
rendering to not look like a man page misused for something else. | |
Anyway, I got three mockups of the same Webzine example and decided to | |
use Scribus to export its version as a SVG file and embed it in a html | |
file for allowing web browsers to display it natively. | |
I asked the Mastodon community (thank you very much to everyone who | |
participated!) which version they liked the most and I got many | |
replies: the mdoc html version was the most preferred by with 41%, | |
while 32% liked the SVG-in-html version and 27% the PDF. Results were | |
very surprising! The version I liked the least was the most preferred, | |
but there were reasons underneath. | |
The PDF version was not available in web browsers (or at least didn't | |
display natively) and some readers didn't enjoy that. As for the SVG | |
version it didn't work well on mobile phones and both versions didn't | |
work at all in console web clients (links, lynx, w3m). There was also | |
accessibility concerns with the PDF or SVG for screen readers / | |
text-to-speech users and I wanted the Webzine to be available for | |
everyone so both formats were a no-go. | |
Ultimately, I decided the best way would be to publish the Webzine as | |
HTML if I wanted it to look nice and being accessible on any device for | |
any users. I'm not a huge fan of web and html, but it was the best | |
choice for the readers. From this point, I started working with a few | |
people (still from the same French OpenBSD community) to decide how to | |
make it as HTML, from this moment I wasn't alone anymore in the | |
project. | |
In the end, the issue is done by writing html "by hand" because it just | |
works and doesn't require extra complexity layer. Simple html is not | |
harder than markdown or LaTeX or weird format because it doesn't | |
require extra tweaks after conversion. | |
# Community | |
I created a git repository on tildegit.org where I already host some | |
projects so we could work on this project as a team. Requirements and | |
what we wanted to do was getting refined a bit more every day. I | |
designed a simplistic framework in shell that would suits our needs. | |
It wasn't long before we got the framework to generate html pages, some | |
styles changes happened all along the development and I think this will | |
still happen regularly in the near future. We had a nice base to start | |
writing content. | |
We had to choose a licensing, contributions processes, who is doing | |
what etc... Fun times, I enjoyed this a lot. Our goal was to make a | |
Webzine that would work everywhere, without JS, with a dark mode and | |
still usable on phone or console clients so we regularly checked all of | |
that and reported issues that were getting fixed really quickly. | |
# Simple framework | |
Let's talk a bit about the website framework. There is a simple | |
hierarchy of directories, one used to write each issue in a dedicated | |
directory, a Makefile to build everything, parts that are common to | |
each generated pages (containing style, html header and footer). Each | |
issue is made from of lot of file starting with a number, so when a | |
page is generated by the concatenation of all the parts parts we can | |
keep the numbers ordering. | |
It may not be optimized CPU wise, but concatenating parts allow reusing | |
common parts (mainly header and footer) but also working on smaller | |
files: each file of the issues represents a section of it (Quote, Going | |
further, Headlines etc...). | |
# Conclusion | |
This is a fantastic journey, we are starting to build a solid team for | |
the webzine. Everyone is allowed to contribute. My idea was to give | |
every reader a small slice of the OpenBSD project life every so often | |
and I think we are on good tracks now. I'd like to thanks all the | |
people from the https://openbsd.fr.eu.org/ community who joined me at | |
the early stages to make this project great. | |
Git repository of the OpenBSD Webzine (if you want to contribute) |