A Publication Style Guide for Linux?

Saqib Ali asks: "Apple, publishes the Apple Publications Style Guide, which codifies the way in which Apple documentation uses language. This publication contains information about the specific terms that are used to describe interface elements. It also defines style and usage issues such as how certain terms are used and the preferred capitalization, spelling, and hyphenation of those terms. Some parts of the style guide are excerpted in this chapter to provide quick reference for key elements of the user interface. Whenever you are constructing a language for your application, you can consult the Apple Publications Style Guide to help you to create consistent and usable one. Is there a similar Style Guide for Linux Publications? If not, why not?"

"My interest in this stems from the fact that there is lot of Linux Documentation (including mine) that are not consistent in the style and terminology. So, I would like to propose a creation of a Style Guide for Linux Technical Publication. I think a wiki would be the perfect tool to create this Guide collaboratively. I am willing to host a Wiki @ http://tools.tldp.org (The Linux Documentation Project development server). Is this a good idea? Are people interested in seeing something of this sort?"

The ultimate irony

[AtariAmarok]

Clippy: "You seem to be writing a Linux style guide. Would you like some help?"

GNOME has one.

[Captain Rotundo]

Available at:
http://developer.gnome.org/documents/style-gu ide/

Discusses mostly how to write accessible and translatable documentation. And includes a standard terminology list.

Haven't read it in a while so don't know how complete it is, also it is probably very GUI/GNOME-centric for obvious reasons.

I am not sure but I would assume other projects (KDE?) have similar documents.

Of course not

[black mariah]

There isn't a general Linux style guide, and probably never will be one. We're talking about a group of developers that can't even agree to use the same damn directories consistantly. How would you expect them to draw up a style guide and then get people to use it? "Well, I like most of the Linux Style Guide, but I prefer to call kernal modules 'sticky-outy bits' so I'm not going to use any of the style guide recommendations."

This is a group of people that fork free software because it's not free enough. Am I being clear enough? ;-)

Re:Of course not

[tka]

But such guides should be created if possible. If somebody would like to code using The Style Guide he/she couldn't found it resulting in more that incosistent code. Creating a guide improves the situation in the long run.

Re:Of course not

[black mariah]

True, and I'd support any effort to make a style guide. I'm not a developer, I'm an end-user, so ANYTHING that makes documentation more consistent is okay with me.

Re:Of course not

[FattMattP]

Your post does not follow the Slashdot Posting Style Guide closely enough. Next time, please use more misspellings and less facts and insightful observations.

:-)

Style and Linux?

[jpsowin]

Have you ever seen the average linux application compares to the average OSX or even Windows program? Style? Linux?

The only time Linux had style was in 1998 when Enlightenment was being actively developed and it made people's jaws drop. But maybe that wasn't style but just effectssomething that Windows or Mac didn't have at the time.

Mod parent down! He hasn't Tried KDE 3.2

[Krik Johnson]

Once again, ignorant moderators are modding up lies! KDE 3.2 is where the style's at, with the screenshots to proove it! [kdelook.org]

paraphrasing Alan Cox,

[Chipaca]

If there isn't one, it's because you haven't written it yet.

Let the holy wars commence

[BenjyD]

After seeing the flame-war that ensued on the KDE lists over whether to use Folder or Directory in dialog boxes, I predict flamewars during the writing of the guide on a scale not seen since the Emacsian Jihad.

IMHO, though, a very good idea - once established, the OSS has a habit of sticking to standards.

Re:Let the holy wars commence

[fm6]

I predict flamewars during the writing of the guide on a scale not seen since the Emacsian Jihad.

Which is precisely why this is a bad idea.

Don't get me wrong -- I'm a tech writer [picknit.com], and style guides are part of my professional toolset. But the point of a style guide is to get a bunch of disparate people writing with a common voice, so that the reader isn't distracted or confused by inconsistent usage. How could you possibly expect anything like a common voice from the odd assortment of volunteers that

Re:Let the holy wars commence

[Krik Johnson]

Folder won! See it in KDE 3.2! Directory has been obliterated!

Down with monolithic running dogs of imperialism!

[paul.dunne]

"Is there a similar Style Guide for Linux Publications?

No.

"If not, why not?"

Because the linux world is not monolithic, and we prefer it that way.

AUISG.

[richie2000]

Just fork the Amiga User Interface Style Guide as Linux User Style Enterprise Recommendations and release it under 4711 different licenses (except that XFree 1.1 one). Then make an rpm, deb, tgz and ebuild for it and you're set.

Re:AUISG.

[stonebeat.org]

I thought forking the SCO User Interface Style Guide. But couldn't find one :(

Re:AUISG.

[richie2000]

Ah, you've been searching for the wrong title. That would be Darl McBride's Illustrated Guide to Forking Everyone in their Rear Orifice and Charging $699 for the Pleasure. I hear it's coming out in a For Dummies version soon.

SCO - Fucking their customers with style.

Design by fiat

[WayneConrad]

Why shouldn't someone make a style guide for everyone? Because Unix doesn't work that way. Let me explain.

The Unix culture loves standards. Standards are yummy. Unix eats standards for between-meal snacks. But what the Unix culture abhores is standards created from whole cloth and handed down from on high.

Why? Is it just because we're just cranky? Well, we can be cranky, but it's not just that.

It's because standards created from whole cloth and handed down from on high are invariably awful. When someone sits down to write a standard, they have the luxury of ignoring vast tracts of difficult territory, of hand-waving away little details like implementation.

That's why the Unix culture prefers its standards to evolve from existing, successful practice. That's why successful RFC's don't create a standard out of nothing, but rather codify something that's already been done. They turn research into production, but the research has to be there first. It has to be something that people see is good, something that with a few tweaks could be a good standard for wider use.

If Unix were to somehow get a unified style guide, it would happen because one of the many excellent existing styles gained the acceptance of the community in general. Then and only then would that style guide be turned into a standard.

Re:Design by fiat

[dilger]

It's because standards created from whole cloth and handed down from on high are invariably awful.

Often true. But many (if not most) documention style guides aren't developed prescriptively, in the manner you describe. They're developed descriptively, from existing documentation. And they're frequently updated, revised, and extended. IMO Apple's style guides are an excellent example of this method of development.

cbd.

Re:Design by fiat

[stonebeat.org]

that is why i recommending a Wiki.....

LDP

[kalidasa]

Just use the Chicago one, add ideas (but not language) from the Apple style guide where relevant, and sprinkle it with the Jargon file for that UNIXy flavor.

In all seriousness, the LDP has a style guide [linux.com], but it looks somewhat thin to me (I haven't read it through though, in best /. style). Publications style guides are for projects that do real documentation. That kind of documentation tends to be unpopular with FOSS, because it requires a level of feature stability that's not common in FOSS, and a certain amount of hierarchical management that's definitely not popular with FOSS. Besides, most people who participate in FOSS are doing so to scratch a development itch, and have a cavalier attitude about documentation. I'd suggest looking more toward a publisher like O'Reilly for a model of how to write documentation.

Style guide

[Skipworthy]

While I agree that one of the best things OSS has going for it is the passion of the developers to make code and applications that are free from constraint, I have to say that one of the greatest weaknesses is the quality of documentation available. Granted, some if it is *great* and there are more than enough sources of good advice, but STILL...it's sure be nice, and it would help *the cause* immeasurably if there were a more consistant and accessible style of documentation.

I can't code, but I can learn to use software, and I can write. Count me in.

I thought there was one

[crisco]

Plain Text!

Apple declines to use foo bar...

[fulldecent]

From Apple's documentaion, page 165:

"Avoid foo, bar, baz opr frobazz to represent hierarchical or ordered metasymbols in code examples."

That's bullshit!

Guide for Linux Documentation

[wehe]

A great way to write program documentation is the usage of DocBook XML (which is in fact sort of a style guide for documentation). This is explained in detail in the LDP Author Guide [tldp.org] (by The Linux Documentation Project), which contains even more information about documentation styles. BTW: IMHO the "success" of Microsoft operating systems is based heavily on their extensive Style Guide.