[FM Discuss] Style Guide?

Sat Dec 5 02:16:49 PST 2009

I could agree with this approach but I would prefer a chapter written in
the FM manual exploring the issue, and accompany it with two example
style guides - one light weight, and one more comprehensive and at
variance to the first. We may wish to highlight that style guides are a
choice not an edict, discuss who might find them useful and who might
find them a hindrance, discuss when in the process they could be
introduced if introduced, other reasons why a style guide might be
interesting to have and why they might not be interesting, discuss
strategies and offer other approaches for creating internal consistency
within a document (including ignoring consistency as a strategy, and
also creating a style guide on the fly as I discussed in a previous
mail). 

but we should keep the above discussion on the subject light weight and
short - one short 'page' if possible.

we could create two chapters in the FM manual under a new section title
'proofing and style':
* about style
* example 1
* example 2

adam

On Fri, 2009-12-04 at 21:21 -0800, William Abernathy wrote:
> Thanks, Adam, for this informative post. This does disabuse me of some of the 
> preconceptions I had held about FLOSS Manuals. I'd also like to thank you all 
> for your other thoughtful responses, and I apologize for those times when my 
> tone has become intemperate. Just as Adam is passionate about this project, I am 
> passionate about editing, and sometimes a bit of lemon juice can squeeze out 
> around the edges.
> 
> While I am tempted to chase down every point everyone has raised, I think we're 
> actually closing in on a possible middle ground. Allow me to draw out an 
> analogy. In American jurisprudence, there are several bodies of law. Something 
> that's legal in one state may be illegal in the next, and something verboten in 
> one federal circuit may well be legal in the next. Informing all these bodies of 
> law are numerous guideposts, foremost among them, the Constitution and English 
> common law precedent. There is also a thing called the "model code," which is 
> not law, which has no value as precedent, but yet is studied by law students, 
> and serves to inform many decisions.
> 
> By analogy, I would say that FM's "constitution" is its licensing structure. 
> When you contribute or use the manuals, there are firm expectations you agree 
> to. And I think we all agree that obedience to the licensing is very important. 
> Likewise, we have group customs, some of which bind together the larger group 
> (FM), others of which obtain only within smaller orgs, such as Harvard's CS 
> department. What I think would work is a style guide as model code -- It's there 
> if you need it, but no one can beat you up over not using it, unless that's how 
> the Maintainer of a particular project chooses to play it. And I believe that if 
> an individual maintainer pays such a guide zero attention or is a complete 
> hardass about style is a freedom and a power we need to confer upon the 
> maintainer. I think the natural evolution of projects will show us the best 
> approach.
> 
> In other words, if we have a model style guide that a project founder can simply 
> download and use at the outset of the project, or not, we can offer editors what 
> they need without spooking anyone off. The founder or maintainer could thus 
> state at the outset (perhaps via a link from the WRITE page) "In questions of 
> style, it is suggested that editors refer to the FM Model Style Guide," or "This 
> manual is unbound by stylistic convention." If the maintainer adopts the Model 
> Style Guide and then finds a point at which this guide is not working, he or she 
> could A) make a judgment call, and make an exception to the guide in that 
> instance, B) make a bookwide exception to the style guide, and note it in the 
> book's document conventions, C) propose/make a change at the level of the Model 
> Style Guide itself.
> 
> Now, on to some of your points.
> 
> adam hyde wrote:
> > hey
> > 
> > There are a number of huge issues here. First, thanks for opening up
> > this conversation, i want to think about this in more detail as I feel
> > my reply could be a thesis if I don't narrow it down. 
> > 
> > But as a first response my main issues are :
> > * FM is a community of communities. 
> 
> <discussed above>
> > 
> > * We are not FM the publisher, we are FM the group of variously
> > connected groups and individuals. Hence I find the idea of a universal
> > style guide inappropriate. If you would like to write one and have it
> > available as an example in the FM manual I might agree with this, but it
> > would need to be brief and come with disclamiers.
> > 
> > * there are indeed FM projects that have found offense in people forcing
> > style guides on them. I have experienced this first hand. 
> 
> On the issue of the availability of a "universal" or "model" guide, I think 
> we're much closer to synthesis here than you might want to admit. I have no 
> objection to a style guide being brief, or referring off-site (for example to 
> Wikipedia's guide or Chicago for guidance) and to come with a lot of 
> disclaimers, etc. that discuss cultural norms peculiar to FM.
> 
> As to the issue of people forcing style guides on each other, I think the fault 
> lies in the person doing the forcing, not the thing they are forcing. If we want 
> to maintain production quality based on cultural norms, rather than standards, 
> that's fine -- I just need a better fix on those norms.
> 
> As an editor, my inclination is to make needed changes, answer any questions 
> that arise, and not fiddle with something twice. If you don't like a particular 
> edit, and you understand the point I've made in trying to correct you, then as 
> far as I'm concerned, you know what you're doing, and I don't fuss if you nuke 
> my edits. If the author or maintainer gets into a throwdown with an editor who 
> can't hear "no," you have identical methods for dealing with that editor whether 
> or not he or she comes brandishing a style guide.
> 
> > * it is maybe my problem that I studied philosophy and so I am aware of
> > slippery slopes. I see this as a potentially very slippery slope. I can
> > see it leading to policing or 'strong coercion' and I do not want that
> > to happen. It might also pay to read up on what is happening in
> > Wikipedia at the moment with record numbers leaving because (amongst
> > other reasons) there are too many rules - they started out with a much
> > more open policy but they now realise the number of policies has serious
> > negative consequences and they are doing what they can to remedy this.
> > 
> > * We are a low overhead, rapid moving organisation. I want to keep it
> > this way. Style guides are a burden to contributing to the generation of
> > content.
> 
> I just don't see it this way. As an editor, a style guide helps me make my 
> contribution, which involves advocating for the reader, and helping organize 
> people's writing to make it logical and conform to accepted rules of grammar. If 
> you misspell a word, it's not the dictionary's fault when I correct you. It *is* 
> my fault, however, if we get into a flame war over it. Same goes for grammar, 
> usage, and style, all of which can be found in a good style guide.
> 
> --William
> 
> 
> 
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net

-- 
Adam Hyde
Founder FLOSS Manuals
German mobile : + 49 177 4935122
Email : adam at flossmanuals.net
irc: irc.freenode.net #flossmanuals

"Free manuals for free software"
http://www.flossmanuals.net/about