|
|
CFT is just as guilty and the projects are not blameless
There are many excellent BSD-related blogs out there.
But they might be harmful however, and Call For Testing was just as much part of the problem.
Why? Because technical blogs often provide "exclusive" documentation that is not available anywhere else but there is no formal pipeline to get that wisdom into upstream documentation. As upstream destinations however, projects have not achieved the "friction-free" contribution experience that some aim to achieve.
This has to change to advance the craft.
To their credit in the GNU/Linux space, the contributors to the ArchWiki have made the resource so authoritative that it is often valuable to non-GNU/Linux users. Hats off.
By contrast, the FreeBSD Wiki has been described as "where good documentation goes to die", which is sad, because the FreeBSD Wiki is one of the most "friction-free" opportunities for people to contribute to FreeBSD documentation.
This has to change.
Blogs like Call For Testing at best get content upstream organically and at worse unintentionally discourage improvement of the official documentation, even if simply for want of enough hours in the day. I shifted from Call For Testing to microblogging on social media platforms and leave my formal documentation to papers and conference talks, but neither is truly upstream.
Admitting my guilt, and I applied to be a FreeBSD "Docs" committer in response to the visceral reaction I had to the Kernel/Debugging crash dump chapter. I was astonished how complicated the committer onboarding process was and I thank you Benedict for your patience. I had fresh "Production User" knowledge to contribute but even the onboarding docs became a tar pit of things to fix. The SVN to Git migration compounded this problem, not to mention the fact that any healthy open source project is a moving target.
Fast forward to mid-2023 and the Jails/Zones Production User group was collectively horrified when we saw the FreeBSD Jails Wiki page. I updated the page based on that visceral reaction but negative visceral reactions are not a sustainable motivator for contribution.
In fact they're terrible, but they're effective.
Around that same time, I noticed that the FreeBSD Handbook Introduction included deprecated platforms and failed to mention that FreeBSD was good for storage and virtualization systems.
I submitted a pull request to the FreeBSD mirror on GitHub to give this contribution vector a try. The result was a five month process, some of which was squarely in my court and some of which was dependent on reviewers and committers. The GitHub mirror is marked "experimental" and has pull request activity on all repos, but does not say much to help set expectations. Thank you Warner Losh, Sergio Carlavilla, and others for overseeing FreBSD pull requests made via GitHub none the less!
So what could we all do to improve the situation?
Keep blogging of course. Your contributions might never leave your notebook otherwise. Do please however think about what content you can upstream and what contribution vector would have the least friction.
In the case of FreeBSD, apply for a Wiki account and give it a go. The Wiki's best content does not receive the attention it deserves but it's a great place to incubate content either way.
Finally, end the pull request experiment, either by sunsetting it or making it an official contribution vector.
I have no opinion as to if pull-requests should go to a self-hosted repo or GitHub because I see the advantages and disadvantages of both.
The daring long-term question is: Should FreeBSD documentation move entirely to a pull-request model? I am in no position to say.
Finally, I am experimenting with Collbora Office for my own self-hosted documentation and I am pleased to report that Production User Call co-host Antranig Vartanian has it building natively on FreeBSD. THIS is exciting news!
Copyright © 2011 – 2024 Michael Dexter unless specified otherwise. Feedback and corrections welcome.