Hi,<br><br>Big companies use style guides to make the documentation anonymous - the documentation created by big technology companies is impersonal and it is impossible to tell who wrote which section in what manual.<br><br>

Use of such style guide might greatly limit the creativity and motivation of an accidental contributor to FLOSS Manuals. First of all it would require contributors to read a huge guide before they actually can write a word - not very motivating. And not all people would even be interested in such things while they would be perfectly able to write nice documentation for FLOSS. <br>

<br>Also it would establish a uniform style that might actually be boring for many people - everybody has their own writing style, why try to change it into something uniform? I mean very different styles would work for different types of manuals. <br>

<br>Regards<br>Tomi<br><br><div class="gmail_quote">2009/12/3 adam hyde <span dir="ltr"><<a href="mailto:adam@flossmanuals.net" target="_blank">adam@flossmanuals.net</a>></span><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

hi,<br>
<br>
ok..I really do not want to see FM adopt a style guide as policy and I<br>
do not want style guide police. I absolutely disagree with your position<br>
on this and I will not support it.<br>
<br>
If you wish to write a style guide and hope others adopt it, fine. But I<br>
will not make it the default for manuals. Style policing will deter<br>
contributions. At the end of the day we are about collaborative<br>
production of content and keeping the doors wide open, letting them do<br>
as they wish, we are not about forcing people to adopt _a_ way of doing<br>
things.<br>
<br>
adam<br>
<div><div></div><div><br>
<br>
On Thu, 2009-12-03 at 11:37 -0800, William Abernathy wrote:<br>
> Hi all. I've been editing for the project for about a month. I am a technical<br>
> editor by trade, and thanks to the current economic miracle, have plenty of time<br>
> to donate to FLOSS Manuals.<br>
><br>
> As I've worked here, I've time and again been struck by the lack of any<br>
> agreed-upon style guide. Questions of style are, as far as I can tell, addressed<br>
> on an ad hoc, project-by-project basis. I believe this is a problem that we need<br>
> to rectify, and would like to propose some solutions and hear your thoughts on<br>
> the matter.<br>
><br>
> First, I'd like to argue the case for a site-wide style guide.<br>
><br>
> 1) A site-wide style guide makes for a consistent product.<br>
><br>
> If I go to FLOSS Manuals and see a manual with strange internal conventions that<br>
> make the work hard to understand, I will be less inclined to return for more<br>
> documentation. If, on the other hand, each FLOSS manual has a consistent style,<br>
> I will be more likely to recognize it as a valuable reference, and I will come<br>
> back for more.<br>
><br>
> 2) A site-wide style guide helps make a more efficient process.<br>
><br>
> I've suggested a site-wide guide to Adam. He suggested I should go to a<br>
> particular documentation project, work on its guide, then see if I could float<br>
> that to the larger group. This is exactly what I'm hoping to avoid. If I (or an<br>
> author or maintainer) adopt a peculiar orthography to solve a problem I have on<br>
> one project, this may or may not be applicable to all projects. Further, my<br>
> "solution" may not be a good idea to begin with. If there is a debate about some<br>
> question of style or usage, say on the Firefox group, once it's settled, it's<br>
> settled there only. If it pops up again in OpenOffice, then the writers,<br>
> editors, and maintainer have to hash it out in their group all over again, and<br>
> may come to a different result.<br>
><br>
> 3) A site-wide style guide makes life easier for editors.<br>
><br>
> As I look at FLOSS Manuals, I see a bunch of non-standard usage. I accept that:<br>
> I'm an American, and my version of "standard" is different from the Commonwealth<br>
> standards that prevail over much of the English-speaking world. When I have a<br>
> tough edge case in my work, I appeal to an established guide -- usually the<br>
> Chicago Manual of Style, but on occasion the AP manual, or Microsoft or Sun's<br>
> style guides. When I write for a corporate client, they usually have their own<br>
> in-house style guide. And on the Free/Libre/OSS tip, Wikipedia has its own style<br>
> guide, which you can see at<br>
> <a href="http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style" target="_blank">http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style</a>. The problem I have right<br>
> now is that I have no court of appeal. Should I refer to Chicago, or AP? Oxford,<br>
> Cambridge, or Fowler? If I can't answer such a question, my choices are:<br>
> A) Don't touch a possible error.<br>
> B) Edit as I see fit.<br>
> C) Bug the maintainer for advice.<br>
> None of these makes sense -- If I leave the error, it stands, and quality<br>
> suffers. If I edit, I may violate a local convention, breaking the work and<br>
> increasing the maintainer's workload. If I bug the maintainer, then I am again<br>
> increasing the maintainer's workload, for something he or she likely views as<br>
> trivial, which leads me to point...<br>
><br>
> 4) A site-wide style guide makes life easier for maintainers.<br>
><br>
> If a maintainer has to make a lot of localized judgments concerning matters of<br>
> style, he or she is drawn away from the many other important jobs he or she must<br>
> handle -- cultural, social, and technical. Further, the kind of questions that<br>
> turn my crank as an editor will likely lie far outside the area of expertise of<br>
> the average maintainer. I can't code my way out of a wet paper sack, and rather<br>
> doubt I have the managerial and interpersonal skills needed to bring a FLOSS<br>
> manual to completion. I respect the maintainer's formidable skill set. This<br>
> said, I do know how to fix documentation, and the less I have to bug maintainers<br>
> to get my job done, the happier both of us will be.<br>
><br>
> 5) A site-wide style guide is better suited to ongoing maintenance.<br>
><br>
> If an end user wants to edit something, or an editor wants to join the party<br>
> later in the development cycle, one FLOSS-wide set of rules will make it easier<br>
> to join in. If you've kludged up a project-local style guide, odds are that a<br>
> drive-by editor (one of my hobbies) is not going to see the book's local MoS<br>
> before plunging in. You want to encourage people to contribute whenever<br>
> possible, you need a single authority with "rules of the road" that writers,<br>
> editors, and maintainers can appeal to A) while they work, and B) should<br>
> disagreements arise over questions of style. Further, if I'm on my game, I will<br>
> remember the FLOSS Manuals style point for the next project I touch, I won't<br>
> have to look it up again, and we won't have to discuss it once, let alone twice.<br>
><br>
> I would like to suggest the following possible solutions to this problem.<br>
><br>
> 1) We could adopt an external reference book, such as the Chicago Manual of<br>
> Style, as a canonical reference. Were we to do this, we would likely end up with<br>
> a much smaller online style guide to handle exceptions. I am uncertain as to<br>
> whether this is an acceptable course for this organization, because A) Chicago<br>
> (or any other MoS) is a proprietary text and as such does not conform to FLOSS<br>
> principles, B) any one volume will not encompass the full scope of international<br>
> English usage.<br>
><br>
> 2) We could adopt the Wikipedia MoS as our style guide. This offers several<br>
> advantages: the manual is universally accessible, free, and libre. While it is<br>
> more rough-hewn than many of the published style guides, it's quite serviceable,<br>
> and will not provide a bar to entry for any contributor.<br>
><br>
> 3) We could generate our own home-grown manual of style. The advantage of this<br>
> approach is that it would be 100% local to FLOSS Manuals and might prove<br>
> valuable as proof-of-concept for the FM development style. The disadvantage is<br>
> that it would be rather time-consuming, would involve a lot of discussion and<br>
> compromise, and would likely take somewhat limited resources away from the<br>
> projects at hand.<br>
><br>
> 4) We could fork the Wikipedia MoS. I don't see the point in this, but you might.<br>
><br>
> In any of these solutions, I foresee that FM will as yet need a site-wide style<br>
> guides to handle exceptions to either a book- or Wikipedia-based approach.<br>
><br>
> Thank you for considering this issue. I know that this will make my editing task<br>
> easier, I believe it will make your product better, and strongly suspect it will<br>
> attract more editing talent to FLOSS Manuals. If people want to SIG this, that<br>
> might be a good way to address it.<br>
><br>
> --William<br>
><br>
> _______________________________________________<br>
> Discuss mailing list<br>
> <a href="mailto:Discuss@lists.flossmanuals.net" target="_blank">Discuss@lists.flossmanuals.net</a><br>
> <a href="http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net" target="_blank">http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net</a><br>
<br>
<br>
</div></div>--<br>
Adam Hyde<br>
Founder FLOSS Manuals<br>
German mobile : + 49 177 4935122<br>
Email : <a href="mailto:adam@flossmanuals.net" target="_blank">adam@flossmanuals.net</a><br>
irc: <a href="http://irc.freenode.net" target="_blank">irc.freenode.net</a> #flossmanuals<br>
<br>
"Free manuals for free software"<br>
<a href="http://www.flossmanuals.net/about" target="_blank">http://www.flossmanuals.net/about</a><br>
<div><div></div><div><br>
_______________________________________________<br>
Discuss mailing list<br>
<a href="mailto:Discuss@lists.flossmanuals.net" target="_blank">Discuss@lists.flossmanuals.net</a><br>
<a href="http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net" target="_blank">http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net</a><br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br>Best Regards<br>Tomi Toivio<br>Open Source Coordinator<br><a href="http://fi.flossmanuals.net/" target="_blank">http://fi.flossmanuals.net/</a><br><a href="mailto:tomi@flossmanuals.net" target="_blank">tomi@flossmanuals.net</a><br>

+358445488856<br><br>