Slashdot Mirror
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?"
Available at:
http://developer.gnome.org/documents/style-g
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.
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, 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.