What does it take to contribute to the Doc section of the FreeBSD community ?

Charlie Brown

Charlie Brown

Hey everyone, hope everything go relatively well for you all in these time,

I'm wondering if maybe I could contribute to the doc section, but since I'm no tech guy, I don't know if I can do anything to help there. But I'm really interested to contribute to that section. What does it take to be able to do it, what is needed, where should I begin and is it possible? Even if it's a small task, I'll be happy to do it.

Would be nice to have feedback from someone who do it or did it in the past.

Thank you !
 
I haven't done anything but send in a little patch or two to a man page. But what I do is put up my own web pages, which include quite a bit about FreeBSD. A better example might be vermaden, who has a great set of webpages, much of it doing with FreeBSD, but covering other related Unix and Unixy stuff https://vermaden.wordpress.com/
Something like that, even if unofficial, would probably be of great help. For example, (not that it's a good one), I spam my pages all over this forum whenever I see a post at least tangentially related to something I've written about.

As for little patches for man pages and stuff, usually it's been something obscure, and I just attached it to an email and sent it to the listed maintainer, though you could, and probably should, use FreeBSD's bugzilla. Patching man pages isn't that hard, you just open one up in vi and you'll see the needed format and tags.
 
scottro

Thanks mate :)

Charlie Brown

If you want to contribute changes to official documentation - then its more or less like that:
  • You 'fork' the 'freebsd-doc' repository - https://github.com/freebsd/freebsd-doc
  • Make all the changes and improvements you wanted to make
  • Submit 'Pull Request' for review of the changes you made

More or less like that ...

There was a time almost two decades ago that I did not follow the rules - and just wrote 'some' update to the FreeBSD Handbook regarding Virtualization topic ... and it was never taken into consideration.

Its still here:

Its now not really useful - but it WAS useful back in 200x when I proposed to make that change.

So ... either you start a blog and do not give a ... if someone will use info from your blog or not ... or play by the FreeBSD project rules and use GitHub and git(1) for the changes your propose.

Hope that helps.

Regards,
vermaden
 
scottro said:
I haven't done anything but send in a little patch or two to a man page. But what I do is put up my own web pages, which include quite a bit about FreeBSD. A better example might be vermaden, who has a great set of webpages, much of it doing with FreeBSD, but covering other related Unix and Unixy stuff https://vermaden.wordpress.com/
Something like that, even if unofficial, would probably be of great help. For example, (not that it's a good one), I spam my pages all over this forum whenever I see a post at least tangentially related to something I've written about.

As for little patches for man pages and stuff, usually it's been something obscure, and I just attached it to an email and sent it to the listed maintainer, though you could, and probably should, use FreeBSD's bugzilla. Patching man pages isn't that hard, you just open one up in vi and you'll see the needed format and tags.
Click to expand...
I'm curious, what is your website ?!
How do we know what is needed? (I mean outside Bugzilla) I thank for the tip I'll go check like now :))
 
Charlie Brown said:
What does it take to contribute to the Doc section of the FreeBSD community ?
Click to expand...
Yes, there are a few issues that require code/technical insight, but you can improve wording, help reviewing differentials, maybe you’re proficient in another language; there is so much to do.

Another task is verification; test claims made in the documentation, Thread 98642 to name a recent example. Note that some projects and thus documentation are imported, e. g. the Heimdal implementation of Kerberos or OpenZFS.

So, what it takes? I’d say it takes high frustration tolerance, being able to take the point of view of novice users (and for English documentation to some degree the POV of non-native speakers), and dedication, striving for perfection.​
 
Kai Burghardt makes an excellent point. As we get involved more and more, it becomes hard to judge what is useful for a newcomer. For example saying just get the tarball and patch it with this patch will probably leave the newcomer a bit frustrated.
We might snicker, but they might have no idea of the syntax of untarring a tgz, or how to patch it. So one would (and you'll see that the handbook and wiki are good about this), write something like download the tgz file, untar it, and patch it with the patch.
Then they will give the actual steps that must be taken.
Then the lines fetch example.tgz tar xvf example.tgz cd example fetch patch.examplefile patch < patch.example

That is give the essential steps that the reader has to take.
 
Technical writing has many nuances.
For example: You should/could prefix those commands with % or a # to denote which elevation you are at (user v root).

There is a lot to writing effectively and it’s hard.

EDIT:
Apparently, there is a Documentation Primer handbook (meaning: I just noticed it was there) so I am striking my comments to allow that doc to make the suggestions.
 
It also takes being willing to play with FreeBSD and verifying that the documentation is correct... For example, I discovered issues with rctl(8), and talked about that in this thread:
Thread rctl-mess-is-it-a-bug-or-mis-config-on-my-end.88423. Dunno what the situation is now, it does merit re-visiting if one is to get an idea of what kind of things are expected in FreeBSD documentation.

I mean, in 2023, rctl(8) was not working as documented. I actually read the manpages, and was saying, "Hey, the manpage says this, but when I run rctl on this version of FreeBSD just now, I get some different results, why?".

It does take being accurate and to be able to stick to a very specific sequence of steps, every frigging time. But at the same time, to be willing to adjust AND document the procedure for yourself, so that you can repeat it for the next version, successfully.

And, having said all that, I still suck at git, and would not be able to create a coherent patch for submitting to review - as things stand now. I played with git, at least, so I know that in my case, it would take practice, practice, and practice again until I get it down. And I do know just how important that skill is for being a contributor to even the FreeBSD documentation project. And I realize that some people can understand git and become sufficiently proficient with it pretty quick. I see a lot such people right here on the Forums, so I have an idea of how I compare to them.
 
Are you (anyone) a programmer?
Do you use a text editor (I mean, using Vi or ee to edit a file is one thing but did you "actually spend hours configuring Vi to your liking" is more what I'm asking)?
 
I'm not a dev/programmer... I use nano and Kate if I need a pure text editor... And I don't spend hours messing with vi, I just minimize my use of it, and spend maybe 5 minutes googling for vi cheat sheets every time I actually cannot get away with NOT using vi - which is not often, maybe a couple times a year.
 
So do you think the adoc style is easy enough to grasp or do you think I should make suggestions on how non-programmers can get their feet wet with syntaxes and document compilers (or would that just overcomplicate things :))?

EDIT: It's probably better to let that doc primer handle all the instructions. Never mind. Sorry for the hijack.
 
astyle said:
And, having said all that, I still suck at git, and would not be able to create a coherent patch for submitting to review - as things stand now.
Click to expand...
Don't let that stop you. You can still create an issue (bug report) with suggested improvement or at least the observed difference between what is documented and what actually happens. *Noticing* something is not right and documenting it (via a github issue or bugreport) is the first step that can save time for others.
JohnK said:
It's probably better to let that doc primer handle all the instructions.
Click to expand...
New contributors should also pay attention to the Writing Style chapter of the FDP.
 
scottro said:
Kai Burghardt makes an excellent point. As we get involved more and more, it becomes hard to judge what is useful for a newcomer. For example saying just get the tarball and patch it with this patch will probably leave the newcomer a bit frustrated.
We might snicker, but they might have no idea of the syntax of untarring a tgz, or how to patch it. So one would (and you'll see that the handbook and wiki are good about this), write something like download the tgz file, untar it, and patch it with the patch.
Then they will give the actual steps that must be taken.
Then the lines fetch example.tgz
tar xvf example.tgz
cd example
fetch patch.examplefile
patch < patch.example

That is give the essential steps that the reader has to take.
Click to expand...
Well I know How to tar untar un tgz, I know my way around the console, and a bit about programming in python. I will tend to never forget the newcomers and give detailed explanation and if I am to do man pages patches I will keep my work and share it else where for review in case it is rejected by does who decide. And I think also that it might be a great way to learn more and more about FreeBSD. Plus like I said it's something that motivate me a lot, participating in documentation and making it perfect, rock solid and simple at the image of our Historical FreeBSD' OS. I greatly appreciate the feedback in this thread, thanks a lot. Hope to be useful for such a great project like FreeBSD. I'm bilingual, I speak two language, my primary one is French, and my second one is English so if you guy want to correct me sometime :) go ahead.

The only thing is that for the following year I might not be fully available because I am learning a trade and I work too. But I'm really interset in it, so I'll find time soon as I can, otherwise I wouldn't have asking.
 
You must log in or register to reply here.
Back
Top