• This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn more.

FreeBSD Handbook Online Documentation Editor

scottro

Daemon

Thanks: 395
Messages: 1,178

#26
And that never happens on the DO site? (I don't know one way or the other.) I have seen out of date articles just about everywhere--I'm the author of some on the CentOS wiki, though I have managed, I think, to mark them as such.

Actually, I think docs by the inexperienced are often more helpful. The expert forgets something that has become second nature to them and that missing step confounds the person with no experience.
 

atomicbeef

Member

Thanks: 19
Messages: 64

#27
Actually, I think docs by the inexperienced are often more helpful. The expert forgets something that has become second nature to them and that missing step confounds the person with no experience.
I would always take documentation written by the inexperienced with a grain of salt because they may not fully understand how the topic works. On the other hand, documentation written solely by the experienced sometimes do miss things that a novice would trip over. The best solution is to have the experienced and inexperienced both contribute to documentation. That way the documentation remains clear to all while still being technically correct.
 

uzsolt

Well-Known Member

Thanks: 49
Messages: 260

#28
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.
I think it's the official. If you want to contribute you should accept its format and its rules. I can ask similar question: why can't edit FreeBSD's man pages online? Or the port's Makefile? It would be easier... ;)
But IMHO if you've a suggestion to better format you can open a bug report and the developers will decide.
 

beastDemian

Member

Thanks: 10
Messages: 46

#29
IMHO the biggest problem with having an online editor (like the one PC-BSD has) is that there is no coherence. Everyone edits random lines. I've seen it in the first PCBSD translation effort. I would start a translation using the formal treatment of a person in spanish (usted instead of tu) and found someone edited my lines because that person disagreed with me and thought we should use the informal treatment (and I wasn't the only one using that convention, meaning a lot of people had their translations overrided for things like this).

There was no plattform for discussing the changes, people just made them. In my opinion, the end result was kind of a mess. At one point, the spanish version of the PC-BSD page was only partially translated and some phrases started out in spanish and changed to english mid-sentence. I'm not opposed to modernization, but there should at least be a review process to catch things like these.
 

wblock@

Administrator
Staff member
Administrator
Moderator
Developer

Thanks: 3,579
Messages: 13,850

#30
This can easily become a flame war, but I'll make some comments in the hope they will be useful as a view from the other side. I'm a FreeBSD documentation committer, experienced with the DocBook markup, have modified the build system, and worked on getting a usable modern translation system for it. I've also used AsciiDoc and rST/Sphinx, two other, "simpler" markup systems, for non-trivial documents.

First, we often get people who say "if it only used easier markup, I'd write tons of docs". This is understandable. But really, the markup is not much more complex than what people use here for the forums. The doc team has frequently offered to add markup to plain text documents, to make it easy for people to submit without learning a markup language at all. We very rarely get takers on that, which suggests that it is not just the markup that is a problem.

Here is the secret: writing documentation is hard. If you think it's a nice but optional extra, you have already missed the point. Writing clear, useful instructions is, in many ways, more difficult than writing a program. A program is easy to test. The environment in which it runs is fairly well-known. Readers of instructions can come from any background, and might or might not know any of the jargon or common practices. Good documentation is tested, reviewed, revised, and reviewed again. By multiple people. It's difficult work.

If you have written documentation, you know this. It is easier for a programmer to simply say "people will figure it out", but we all know that's not true. FreeBSD is famous for its documentation, and that is because of the effort people have put into it.

Wikis are an example of simplified, more "accessible" markup. Wikis lower the bar to entry by lowering the qualifications. It's probably possible to have a wiki that is of the same quality level as the Handbook, but it will require serious editors. Lots of them, because editing what someone else wrote is harder than just writing it yourself. For one example, see Wikipedia.

Finally, about those simplified markup languages. They mostly seem to follow the same pattern. DocBook is "too hard", so we are going to simplify it. So quotes means typewriter font, backticks means command or filename, stars means bold. This works fine for very simple, short documents. It fails miserably for documents like those we routinely deal with for FreeBSD. For instance, what if you need to differentiate between a filename and a command? A backtick could mean either... so the simple language becomes more complicated. Now you have ugliness like :file:`/etc/rc.conf`. In DocBook, that is just <filename>/etc/rc.conf</filename>.

We have two big problems I would like to fix. One is our problem with whitespace. I've talked about this at BSDCan and other places, so this will be brief: people editing docs have to separate content and whitespace changes so translators don't end up repeating work they have already done. This is a problem for everyone, and using PO translations addresses it. That's been a project for me for the last couple of years. It also makes translating much, much easier. (See the video: Improving the FreeBSD Translation Tools. My voice barely held out for that talk, but it's understandable.)

The second problem is the formatting rules we have for our XML source files. These are, I feel, overly strict. We should have a program that reformats input to have the correct indentation and so on. At least two people have sworn to me that would be easy with a simple XSL transform. Yet nobody has ever done it, which, as Benedict Reuschling pointed out so aptly, probably means it really is not easy to do at all. I've written textproc/igor to automate the checking of many of these rules, and this makes it much easier for the writer.

If you are interested in the FreeBSD Documentation, I urge you to check out just the Quick Start section of the FreeBSD Documentation Project Primer: https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/overview.html#overview-quick-start
That nine-step example shows how to install the tools, check out the documentation, and begin editing. Try that, and see if it is still so scary.
 
Top