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.
(HTM) 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.
(HTM) Git repository of the OpenBSD Webzine (if you want to contribute)