FreeBSD Handbook Online Documentation Editor

Remington

Remington

Why can't FreeBSD have online documentation editor for its official Handbook? It certainly will make things much easier for contributors to edit and update the Handbook online rather than installing CVS and trying to figure out how to use it. Personally, I think CVS is great for code maintainers but its terrible for Handbook documentations as editors are not programmers.

I had a discussion about this in another thread as one user was confused about using mergemaster as Handbook documentation was not clear on this subject.

I would like to suggest FreeBSD to use something similar to what PHP is using. They have wiki to track internal development for their projects (https://wiki.php.net) and doc online editor for PHP Handbook (https://edit.php.net). If you visit PHP Handbook (http://php.net/manual/en/index.php) and you will see 'edit' at the top-right corner and that will take you right to the online document editor to edit that specific page. Online Handbook document will have revision control. It will be great for FreeBSD to have something similar to what they are using to make editing documents much quicker and easier.

I would be far more happy to contribute my time to online documentation if it will be offered on FreeBSD. We're not in 20th century anymore.

Your thoughts?
 
The problem I see with a wiki based solution is that it's not easy to export it to other formats, while keeping the same "look and feel". Currently the handbook (and other documentation) is written in such a way to facilitate easy exports. The online handbook is basically a HTML export. But you can just as easily export it to PDF or any other (current or future) document format.
 
drhowarddrfine said:
https://wiki.freebsd.org/
Click to expand...

I am familiar with https://wiki.freebsd.org/ for tracking projects but I'm talking about the official Handbook. If you go the FreeBSD Handbook page, you won't see the 'edit' anywhere to edit the document online. That is the main issue. You have to install CVS, setup the configurations, pull in the docs, locate the file to edit and submit to CVS. Doing it online will be far more quicker with less hassles.
 
SirDice said:
The problem I see with a wiki based solution is that it's not easy to export it to other formats, while keeping the same "look and feel". Currently the handbook (and other documentation) is written in such a way to facilitate easy exports. The online handbook is basically a HTML export. But you can just as easily export it to PDF or any other (current or future) document format.
Click to expand...

I know wiki based solution have their own syntax and its not easily exportable to other formats.

Have you checked out https://edit.php.net to get the feel of how their online documentation works? FreeBSD Handbooks and other articles are stored in XML format just like PHP Handbook. FreeBSD could implement something similar to PHP's Docbook Online Editor and I think it would be a better solution for FreeBSD Handbook and other articles.
 
Remington said:
FreeBSD Handbooks and other articles are stored in XML format just like PHP Handbook.
Click to expand...
I had some time time to mull things over while driving home. But I can imagine a Wiki that saves pages in the same XML format. When you save the changes it automatically creates a SVN commit. So instead of a file-based or database back-end it would use SVN. That would allow it to integrate into the existing system. I'm not aware of any existing Wiki that does this though and it would probably need to be written from scratch. But this might be a cool Summer of Code project for someone.
 
wblock@ is involved with FreeBSD documentation, and I'm sure he'll appear and comment on this soon, but I'll take a wild guess that having the Handbook available for anyone to edit is a problem for an official document. FreeBSD prides itself on its documentation but it's not my place to state how this is handled.
 
drhowarddrfine said:
@wblock is involved with FreeBSD documentation, and I'm sure he'll appear and comment on this soon, but I'll take a wild guess that having the Handbook available for anyone to edit is a problem for an official document. FreeBSD prides itself on its documentation but it's not my place to state how this is handled.
Click to expand...

It's not going to be any different since online editor will be using CVS and anyone can edit the document if they want whether using vim or online editor. That's the whole purpose for having CVS is to maintain control on the documents against malicious editors. PHP even allow anonymous user to edit their PHP Handbook. They can decide to turn it off and allow approved users to edit their documents. I'll wait for wblock@ to chime in with his opinion.
 
But then they have to go through all the insane comments and I can see that really ticking people off making them want to give up. Been there, done that.
 
Sorry, don't have time to give more than a cursory response at this point, in no particular order...

CVS has not been used for years, so if you see anything suggesting that, it is far out of date and needs to be updated.
Wiki documentation is almost always a nightmare. I've told people, only half-joking, that wikis are where documents go to die. Beside the documents being enter-and-forget, there is the question of how you verify that the information is correct.
In FreeBSD, the existing mechanisms for pointing out a problem with the Handbook are PRs/bug reports. These are not ideal, but it's what we have at present.
Some thought has been given to making it easier to become a doc committer.
 
I'm not a big fan of wiki either for number of reasons like exportability and security. However, PHP's Docbook isn't wiki.

Have you looked at PHP's Docbook Online Editor? What are your thoughts about using similar features for FreeBSD Handbook? Personally, I think it'll be a great idea to have something like that for doc committers, reputable contributors and users to edit the Handbook. I'm not in favor of allowing anonymous users to edit the docs since folks from Linux camp might do something malicious. Therefore the process needs to be simplified and easier for trusted users to edit the docs. There are several places I would like to edit in the Handbook but current system isn't convenient and many others feel the same way.

In addition to 'edit' button to the Handbook page; 'report' button can be added to report any inaccurate information to doc committers. There are thousands of FreeBSD users and they can spot inaccurate information and can edit the docs or report it. It's far easier than having to use PR/bug report. Honestly, I won't bother doing PR/bug report on docs because its also not convenient, waste of my time and not a high priority for me. Having a 'edit' button on the page will greatly simply the process and reduce much wasted time in editing the docs.

Seriously, why would docs need to have PR/bug report? It's not a source code where it needs to be verified for security and stability.
 
I'm with you, Remington. I personally wouldn't mind 'adjusting' the Handbook myself, because, let's face it, it's often a landing place for search results (that, and the forum). However, the logistics behind it are none negligible. Proof of that is that the Handbook is getting behind in some areas for a lack of resources, and it's quite understandable. There are lots of topics to cover, and FreeBSD is growing every day. I too would like this simple EDIT or REPORT button if allowed this privilege.
 
fossette said:
I'm with you, Remington. I personally wouldn't mind 'adjusting' the Handbook myself, because, let's face it, it's often a landing place for search results (that, and the forum). However, the logistics behind it are none negligible. Proof of that is that the Handbook is getting behind in some areas for a lack of resources, and it's quite understandable. There are lots of topics to cover, and FreeBSD is growing every day. I too would like this simple EDIT or REPORT button if allowed this privilege.
Click to expand...

Forum is a good resource to find solutions but sometimes I just don't have the time to read 100 posts until there's a solution or maybe none. Handbook will provide a perfect place for better techniques, known problems and solutions on the spot. FreeBSD is evolving so fast that Handbook is not catching up fast enough to keep up with the new features and changes so that's why I think it needs better and easier editing capability to allow trusted users to edit the docs. There are many experienced FreeBSD admins or editors who will be happy to edit the docs quickly if they are given the opportunity to do so to unburden doc committers' workload.
 
drhowarddrfine, updates absolutely don't need to be a chapter at a time. Sometimes, just a little paragraph edited in less than 10 minutes can make the whole difference for the user's understanding. That's the objective to achieve. Done several times, and you have a living and more pertinent documentation, well, just my opinion (and perhaps Remington's ;)).
 
I'm going to just add a single comment to this thread, then back off, because I doubt it'll go anywhere productive. If I'm proven wrong, then all the better...

Technology is an artifice. It's a human construct. All technical "failures" are at heart human failures. whether the cause is an innocent mistake, incompetence, ignorance, or laziness. We consider at least two of those things to always be character flaws, and for good reason.

The opinions of people who learn to use the tools competently and actually do the job, but find it unnecessarily difficult, will always carry a whole hell of a lot more weight than people who don't do the job because they find it difficult. This "I would totally help out this cause if someone would only make it easy for me" stuff is hot garbage.
 
ANOKNUSA said:
The opinions of people who learn to use the tools competently and actually do the job, but find it unnecessarily difficult, will always carry a whole hell of a lot more weight than people who don't do the job because they find it difficult. This "I would totally help out this cause if someone would only make it easy for me" stuff is hot garbage.
Click to expand...

You don't have to be a car mechanic or engineer to drive a car because you want a car to be easier to drive. Technologies are evolving faster everyday and it is stupid to be stuck with 20th century technology. It's wrong to call people lazy because we're supposed to make it easier for them for number of reasons. They don't have the time, commitment or technical knowledge like we do and like fossette said, some will be able to edit a paragraph for 10 minutes rather spend 30 to 60 minutes trying to figure out how to install subversion, configure SVN, pull the documents, locate the document, learn how to use vi editor, make changes to the document, commit the document to repository and hope the document is displayed correctly in the Handbook. They have wasted so much time for simple 10 minutes editing job especially for someone who is not a regular contributor nor paid to do the work. Having an 'edit' button on the Handbook will make a big difference.

You might be old-school (no offense) but it's unfair to call people lazy because you expect them to get their hands dirty like a car mechanic.
 
drhowarddrfine said:
That's the sort of person who should not be editing the official Handbook which is what he and I are trying to point out.
Click to expand...

However, it doesn't give you the rights to decide who gets to edit the doc. So you will reject a FreeBSD system admin with 10 years experience and exemplary technical writing skills from editing a document for 10 minute even he never joined, made a single post on the forum or contributed anything? What about a technical writer who have limited technical knowledge of FreeBSD but understand enough to rewrite a paragraph on installation process for new FreeBSD users who knows nothing about the operating system for them to understand clearly?

It clearly shows that you prefer FreeBSD to be an exclusive club and if that's the case then Handbook will be outdated and left behind. Digital Ocean have well written FreeBSD documents, of course, writers were paid to write. So what is wrong with FreeBSD Handbook that prompted Digital Ocean to write their own? Maybe the explanations in FreeBSD Handbook wasn't clear enough for someone who never heard of FreeBSD. They could simply add a link to FreeBSD Handbook.

https://www.digitalocean.com/community/tags/freebsd?type=tutorials

Even PHP Docbook allows anonymous users to edit their Handbook and they don't have problem with that. If they clearly had problems, then anonymous users will not be allowed to edit at all. Why should FreeBSD be any different?
 
Remington said:
it doesn't give you the rights to decide who gets to edit the doc
Click to expand...
I most certainly believe it does. One needs to protect the family jewels!
Remington said:
you will reject a FreeBSD system admin with 10 years experience...
Click to expand...
You presume too much. Someone must edit contributions so accepting and rejecting of such things will happen regardless.
Remington said:
So what is wrong with FreeBSD Handbook that prompted Digital Ocean to write their own?
Click to expand...
First, I'd bet DO's version is not as complete as FreeBSD's. 1A) Those are tutorials, not a Handbook.

Second, supplying documentation on how to use FreeBSD on DO's servers is sort of a requirement if one wants to sell the product and, third, if people are going to DO for articles on FreeBSD usage, it's easier to make a sale.

Note, I said "articles". I don't recall seeing a Handbook of any sort there. I just noticed they are called "tutorials". The FreeBSD Handbook is not really a book of tutorials.

What other people do with their technical documentation has no bearing on what FreeBSD should do. Warren already stated what I had said, that editing contributions from just anyone can be a nightmare. You can sometimes see technical docs get edited, then changed, within hours of each other along with an obligatory online fight among editors and contributors.

There will always be editors. And, like I said, you can contribute to the FreeBSD documentation now. There is nothing stopping you.
 
Facts checking and peer review are still a thing and the system you're proposing promotes neither of them. It would also put the pressure of accepting or rejecting the changes on one single entity, the wiki admin or wiki admin group that may not have a single bit of interest in (m)any parts of the contents of the wiki because their interests are in just keeping the system running. Either way the changes have to be put under public scrutiny before accepted and I don't see anything wrong with current method.
 
kpa said:
Facts checking and peer review are still a thing and the system you're proposing promotes neither of them. It would also put the pressure of accepting or rejecting the changes on one single entity, the wiki admin or wiki admin group that may not have a single bit of interest in (m)any parts of the contents of the wiki because their interests are in just keeping the system running. Either way the changes have to be put under public scrutiny before accepted and I don't see anything wrong with current method.
Click to expand...

Nothing will change on the back-end of the FreeBSD server. All the contents, sources, articles, documents, files, etc., and everything will remain the same. What I am saying is that there should be a need for front-end editor that interfaces with the back-end via SVN commands. It's just the same method as using CLI to pull in the docs to edit and then submit the doc back to the server but it's a lot easier to have the front-end editor to do the same thing. That is exactly what PHP Docbook is doing. It's not a wiki nor quick-n-dirty editor where anyone can edit the docs on the fly without supervision, fact checking, peer review or revision control. PHP Docbook have all the controls already in place including revision control and they pull in the doc using SVN. Sticking with CLI is old school and users will be less likely willing contribute this way. If you didn't bother to look at PHP Docbook then you should not be commenting here.

One thing I like about PHP Handbook as they have 'edit' button at the top-right on their page. I can click on it and it'll take me directly to PHP Docbook Editor and it'll fetch that specific doc. I will be able to view, edit and then commit the doc without having to dig around in the file directory to locate a specific document. Anonymous users can commit the docs once reviewed and approved by the doc maintainers. Those who have commit privileges can submit the document immediately to the main repository.

It's really simple and all the controls are already there. Also, there won't be any need to install subversion client, setup configurations, fetch the doc, etc. with so much time wasted because the online editor with subversion capability is already there.
 
drhowarddrfine said:
First, I'd bet DO's version is not as complete as FreeBSD's. 1A) Those are tutorials, not a Handbook.

Second, supplying documentation on how to use FreeBSD on DO's servers is sort of a requirement if one wants to sell the product and, third, if people are going to DO for articles on FreeBSD usage, it's easier to make a sale.

Note, I said "articles". I don't recall seeing a Handbook of any sort there. I just noticed they are called "tutorials". The FreeBSD Handbook is not really a book of tutorials.
Click to expand...

I never said DO have their own FreeBSD Handbook. I merely said documents and DO's documents are clear, easy to understand and well-written.
 
Remington said:
I never said DO have their own FreeBSD Handbook.
Click to expand...
Remington said:
So what is wrong with FreeBSD Handbook that prompted Digital Ocean to write their own?
Click to expand...

I've noticed their docs also have some inexperience built into them along with DO specific settings and information, as its intention is. You can go and find lots of tutorials on the internet that are pretty good compared to the Handbook. Warren has some excellent docs on his site, too.
 
You must log in or register to reply here.
Back
Top