About documentation.

Alain De Vos

Alain De Vos

People helping writing FreeBSD Handbook.
They are not in center of scenes.
Not writing any "big kernel scheduling code".
But are doing a great job.
Big thanks to them.

And trust me sometimes i use NixOS. It will take them decades to come to same level as quality.

But writing documentation for FreeBSD, why ? It does not make you a code hero. But the importance can not be underenstimated.
 
Respect for the writers. My homage:

Crumb 127: The Writer Wrote and Wrote: The writer wrote, and wrote and wrote. She wrote stories, recipes and novels. She wrote awake and sometimes not. She wrote in dreams and feverishly so. The writer wrote, and wrote and wrote. The writer wrote her life; and her life wrote and wrote.
 
When I still worked instead of trying to succeed as a writer, besides programming and system administration, I also did a ton of user-manual and documentation writing (I'm very versatile), so I know that it is demanding work that requires, among other things, great attention to detail.
 
Everone does what he is good at. I happen to be "second level support engineer".
This means you problem, i analyse. But I totally have no knowledge about sh-shell/C/C++. But if you installed wrong driver i'll try to help.
Thing is we all make are simple part.
Alfredo did you know "pkg update" failed once whole world.
I was the first to notice.
I did almost nothing but guided to "big developer behind the curtains'.
And he solved issue in 2 hours...
 
MG said:
Is there any summary of still wanted FreeBSD documentation?
Click to expand...
According to ChatGPT:
Yes, but there is no single authoritative, curated “documentation wanted” list.

The closest things are:
  • FreeBSD Bugzilla → Product: Documentation — probably the most practical backlog. It contains concrete outstanding work for the Handbook, manual pages, website, and related documentation.
    Open Documentation PRs in Bugzilla
  • “Contributing to FreeBSD” → What Is Needed — the official overview. It specifically asks contributors to find outdated, ambiguous, poorly explained, or incorrect material in the Handbook and FAQ, and points newcomers toward Junior Jobs and the Ideas Page.
    Contributing to FreeBSD
  • The Developers' Handbook and Architecture Handbook explicitly note that some sections do not yet exist and others need updating. Those books therefore represent substantial standing documentation work.
    FreeBSD Developers' Handbook
For someone looking for specific documentation that FreeBSD currently wants written, Bugzilla's Documentation product is the most useful starting point. The other pages describe broader needs, while Bugzilla provides discrete tasks that can be completed and submitted.
Edit: I love it when an LLM says "Yes," but in reality it should say "No." It happens a lot with ChatGPT.
 
Alain De Vos said:
It does not make you a code hero. But the importance can not be underenstimated
Click to expand...
My thoughts too, writing documentation requires some skills, it's not a simple task, that should explain why we can't find it everywhere.
I think about it every time I read a mediocre Linux man page, BSD man pages are unmatched, written by people who just want to share knowledge.

From my point of view, a project needs very good documentation, or very polish man pages, or even better both of them, otherwise it's a project I won't even bother trying.

Some README on github/codeberg/etc are so difficult to comprehend, massive amount of technical details are thrown there for no reason, you already feel the struggle just to explain the basics, sometimes when it's the case I don't even want to proceed any further.

PS:
Bonus point to those who let people download their documentation as pdf, html, zip, etc ... Yep I prefer to read offline it feels more comfortable.
 
Crumb 2226: Ode to Documentation: Don't lament: / document. / Forgetting don’t pretend: / document. / So others your program don’t resent: / document. / And to those who / others’ work document, / no one ever knew / better recipients of a thank-you sent.

Note: Written just now for this thread. Written, actually, in this text box.
 
I do find that when I don't understand something, if I try to document it, it will help my understanding. Some of these turn out to be useful web pages, many others are just in a file on my main machine, in a directory of text files with titles like zfsnotes, usefulSSLcommands, etc.
I think someone on these forums have mentioned that they do this, rather than make "official" FreeBSD or other documentation. If you find it difficult to document under FreeBSD rules, but feel you have something to add, make a little web page about it, or use another way to get it out there to help people.
 
scottro said:
I do find that when I don't understand something, if I try to document it, it will help my understanding. Some of these turn out to be useful web pages, many others are just in a file on my main machine, in a directory of text files with titles like zfsnotes, usefulSSLcommands, etc.
Click to expand...
Any pile of personal text or HTML files is useful today because it's easily searchable.
 
You must log in or register to reply here.
Back
Top