Style guide options?

Get Started
1

Hey guys,

My team is going to start working on a style guide for our company’s website. I have never created a style guide before but there are obviously many many resources on what to include in them. I feel like I have that information down but there are really no resources on the best format to create the style guide in.

The way I see it we have 3 options. We could either create a PDF document, create a wiki, or create an internal site with something simple like wordpress and just use it as a documentation website.

What do you guys think? What have you all done? The obvious problem with the PDF is that it’s not as dynamic. Its amendable but a web-based guide would make changes much much easier. My problem with a wiki is that I’ve never created one before, but I’ve also never looked into it or how easy it would be and wikis are the king of dynamic documentation. I’d love to learn if it seems like the best option. And my problem with an internal site using a CMS is that we would probably have to go through a ton of request protocols before we would get a database created/get access to it (this is a decent sized company with a decent sized IS department.) It would also require a lot of layers of customization to get it to act like a wiki if we wanted to turn it into one. Also my only experience with CMSs is Wordpress so if there is another CMS that would suit these needs by all means make suggestions.

If you guys have any thoughts at all please let me know! Also (mods) if this isn’t in the right forum please move it as you see fit. Thanks for your help everyone :slight_smile:

2

I do a lot of work in the tech writing sector and style guides for us are mandatory for every project. There are a few key lessons I’ve learned over the years about them as well which I’m sure some of you will agree with and some of you will disagree with.

Firstly, using a wiki for a style guide is not a good idea. Any tool that allows continual update or uncontrolled change in a style guide is to be avoided. Wikis generally offer too much scope for change by the community unless write access is tightly controlled.
Your style guide should only be updated frequently in the very, very early stages of a project. Updating style guides in mature projects can be damaging for delivery schedules and costs as the changes have to be cascaded, causing rework in some cases. This is less of an issue admittedly on web development where strategies like CSS are used for example.
Necessary changes as the project proceeds should be subject to a robust review process before being allowed to be incorporated. In my experience style guides should only be changed when absolutely necessary.
Style guides should be cross-referenced from the documented production processes and, believe it or not (and I know you won’t), we got best results from giving our technical writers hard copies to have on their desks for ready ref. Admittedly, our style guides are rather large and are compiled together with SGML business rules.
If anyone’s interested, I wrote an article quite a while back on style guides.

3

Great thanks a lot! A CMS sounds like the way to go.

4

1. Who will need to access the guide?
At the moment, our web design team and anyone creating something user experience related. We’d like it to be scalable though for a larger team, however our company has a very small web team at the moment and it would be hard to imagine it growing too much in the next couple of years. So far we have a pretty good grip on everything that falls onto us.

2. Where will they access it from? (eg workstation, home, on the move)
Most likely workstation, possibly from home if circumstances arise.

3. What devices might they view the guide on? (PC, laptop, phone, paper copy)
Probably a personal computer and/or paper copy if applicable (pdf)

4. Will the guide be frequently updated?
It shouldn’t need to much updating but our team is relatively new and we are slowly revamping the site that was created by a firm who specializes in creating sites for more conservative companies. It is fairly outdated and I foresee design changes in the future. This is the long term driving force for the style guide. We’re thinking more for the future than the next 12 months.

5. If updated frequently how do you communicate that fact, and how quick do changes need to be implemented?
Not very quickly. This isn’t a HUGE priority. Our company has a long track record of planning very far ahead and that’s why we do so well. We sort of have the same philosophy in our department, and that’s why we want to develop a nice clean, somewhat scalable and dynamic style guide now rather than wait a few years when we’re knee-deep in header styles :eek:.

6. What technologies do you and your authors have at their disposal?
We have the hardware, software, and ability to learn just about anything we need to if necessary. We have nearly unlimited resources for a team of our scale.

7. Is the guide likely to cover a dozen items or hundreds?
Probably a few hundred maximum if we start including spelling.

Thank you all for your help. And ShyFlower, those were kind of the same things I was thinking. I’m leaning toward a CMS at the moment, especially considering the scale of our team who will most likely be the only ones using it. We could just set up admin/editor accounts for the few we will trust to change the guide and it would be pretty simple. Any other ideas are welcome! Thanks again!

5

I want to know what is the best way to bundle all of that information. I also clearly stated that maybe this IS in the wrong forum, but there are really no other forums to put it in.

How about 1) Insuring the CMS can do some of the basics, like pullquotes? Or how to structure a forensic analysis (project postmortem). Lab reports, Or Plog? (not a misspelling).

I’ve been a part of teams where I was the only one who even bothered closing out trouble tickets, let alone writing them in a correct format.

I found it difficult to find the markup for a simple Question and Answer: I seriously doubt the CMS is set to support all it needs to.

I understand all of that.

You know all about plogging? You read a lot about brand journalism, maintaining brand messaging across a variety of media, did you? How about the style guide for commenting code so as to be understood by others?

Well that is peachy. Care to share for those who might not want to spend all those hours?

Given it might not be the right forum, might it not be a charitable gesture to “fit in” by providing, say, three interesting things that surprised you when developing your guide.

Finally, one way to bundle it would be templates, just regular pages within a CMS, demonstrating why the various decisions which went into the style guide were made. Wait, what? The CMS wasn’t set up so a contributor could simply select a template, the way they do in Word? Well how about that.

6

The OP was not asking for advice on the content of a style guide

Yes. Why talk about the content of a style guide, what that guide should cover, who the users are, or if the lack of a guide is causing any specific problems when posting in a content writing forum.

FWIW, I used to frequently refer to our corporate style guide (I don’t need to now because I know most of it off by heart!), which is available on our intranet as a PDF and is periodically in the ‘featured links’ on the intranet home page. I also use it as a tool to beat my boss with, when she goes against the style guide.

Could very well be worth a lot …if there was a scrap of information on whether the contributors are anything like you or your situation. As there is no context for providing advice for a defined user or group of users, what they’re doing or what the style guide is supposed to do, all we get to give are our favorites list of technologies.

Move the thread. Or more people are going to mistake this thread for something about content or writing.

7

It depends how dynamic you want it to be. If it’s going to be the case that the marketing executives go into a room, write a document and then periodically amend it to take into account new developments, a PDF would be fine. To be honest, if you have more trouble updating a PDF document (open original in word processor of choice, amend, save, export to PDF) than a web page, I’m worried. An obvious advantage of PDF format here is that it is a little easier to get the exact typography and layout required, which may be important. (It shouldn’t be difficult in HTML, but just occasionally you might hit a snag).

A wiki is particularly useful for a “living” document that anybody can update. That doesn’t sound appropriate for a style guide to me … you don’t want anybody and everybody putting their oar in and making changes to it.

I would usually go with whatever format the rest of your intranet principally uses, with a vague preference for PDF because it will make your life a whole heap easier than learning something new and getting it approved by IS…

8

It is simply amazing how it’s still all about the technology …and not about the style guide. Really, not one syllable about the style guide – think about it. At this point I wonder if the guide would even influence the Wordpress site development, the wiki, let alone the style of writing.

“Without content creators, there would be no need for a CMS. Yet surprisingly, this user group is often the worst served by a new content management system.”
– James Robertson

Has anyone discussed the likelyhood of that PDF ever affecting any human user? In one year I’d wager you’ll be hard pressed to find anyone who can even find the PDF.

But given this is a typical technology solution – sans problems – the actual users writing content would seem to be unnecessary.

Maybe we’re talking about the style of technology, in which case it makes no sense to talk about it here. However moving it to where it belongs bodes ill for the actual guide (should anyone ever eventually develop some interest in the purpose for the technology.)

What this thread needs is a content strategy intervention. Or for the admin to move the thread to a more content irrelevant, user irrelevant, technology scouring the landscape in search of a problem section.

Related:
PDF: Unfit for Human Consumption Let alone that the Microsoft Word template used likely won’t follow the style guide either, and good luck translating what you can do in Word into what your CMS can do.

Frankly I doubt any links on actually developing and implementing a style guide would even get a click.

9

The OP was not asking for advice on the content of a style guide, but was asking about the best format to use, out of PDF, CMS or wiki (“I have never created a style guide before but there are obviously many many resources on what to include in them. I feel like I have that information down but there are really no resources on the best format to create the style guide in.”), so that was the question being answered.

For what it’s worth, I find the Guardian Style Guide is generally pretty good, although there are a few points that I would disagree with if I was creating my own guide.

Has anyone discussed the likelyhood of that PDF ever affecting any human user? In one year I’d wager you’ll be hard pressed to find anyone who can even find the PDF.

FWIW, I used to frequently refer to our corporate style guide (I don’t need to now because I know most of it off by heart!), which is available on our intranet as a PDF and is periodically in the ‘featured links’ on the intranet home page. I also use it as a tool to beat my boss with, when she goes against the style guide.

10

These three points all suggest a web based system, the “current” PDF(s) could be downloaded from the “site”. So non-company people cannot access it you’d need to password protect the “site”.

A CMS sounds in order so you can maintain it easily, I’d suggest something that has the ability to:

  1. Authenticate users via a login system
  • logins would be per person so everyone has their own user/pass (useful for tracking last logins, usage etc)
  • relevent permissions for admins/editors/authors and “view only”

  1. Able to filter “styles” by type and need, eg if I want to be able to see styles for “postal addressing for stationery” I should be able to filter results to show exactly what I need.

  2. Ability to browse styles by type (eg browse headings styles), or browse by need (eg browse all ‘stationery’ styles).

  3. Ability for editors/authors to add notes, annotations and examples for each style type, and possibly variations of. A CMS with multiple custom fields would be perfect here.

  4. Ability to email users to inform them upof updates and so on. Again this could be by user type so if the update only affected “authors” you’d only send to them.

  5. Ability to add PDFs for download as required. You may need to split PDF’s by inerest area etc.

11

The questions bluedreamer posed are good ones, but in reading what you have written so far, I think a simple CMS would be best. In something like WordPress, you have control over who has editorial privileges and who can “read only”. You can also allow some users to add content, but allow an administrator or others with more privileges to review and approve any changes before they are ‘live’.

Wikis can get messy. That’s why you see comments like “citation needed” and “weasel words” spattered all over Wikipedia. Anyone can be an editor and I don’t think that’s what you want for a style guide.

You are right about PDFs. Although newer additions are more dynamic, they can still be very difficult to edit. I think you would end up with a lot of addendums and sticky notes that would make it hard to follow and often in need of complete revision.

You could organize your guide into different pages in a CMS. For instance, you might have a page with words to avoid, another page with preferred spellings (web site or website) A page about capitalization (Internet or internet). Another page with reference links such as the Chicago manual of style, an online thesaurus, or some of the great writing references you find online.

Organization such as this will make it easy for your writers or editors to answer any questions they have about formatting, punctuation, spelling, grammar, etc.

12

Yes, you’re right. Let’s answer a question that the OP isn’t asking, and ignore what he is asking. While we’re at it, why not take a look at his business plan and see if we can improve turnover as well? :rolleyes:

Move the thread. Or more people are going to mistake this thread for something about content or writing.

Fair point, but that’s one for the Advisers to decide - now that it is here, there’s nothing the OP can do about it. I assume you’ve red flagged it rather than just shouting abuse? In the meantime, how about some constructive contribution … or some peace and quiet so the rest of us can do our best to help.

13

I think you need to ask some initial questions first:

  1. Who will need to access the guide?
  2. Where will they access it from? (eg workstation, home, on the move)
  3. What devices might they view the guide on? (PC, laptop, phone, paper copy)
  4. Will the guide be frequently updated?
  5. If updated frequently how do you communicate that fact, and how quick do changes need to be implemented?
  6. What technologies do you and your authors have at their disposal?
  7. Is the guide likely to cover a dozen items or hundreds?

If you can answer those questions that will give us a good platform to suggest possible solutions.

14

DCrux, why are you being so so sassy? Are you sucking on lemons in your spare time? :confused: The sass is through the roof, guy. Take it easy. I clearly stated that I understand the content of a style guide. I’ve spent a good amount of hours reading documentation on what to include in a style guide. I understand all of that. I want to know what is the best way to bundle all of that information. I also clearly stated that maybe this IS in the wrong forum, but there are really no other forums to put it in. Go through all the forums available and tell me which one would be more suited to this post. Even if you can find one, I bet you’d be hard pressed to find one that you would expect relevant responses from. If you can find one, great, move it, I’m fine with that, I’m just trying to get answers.

But think about it. Who is most likely to have experience writing style guides? Programmers? Web hosts? Marketeers? Or content writers? I put this question here because I knew the experts that frequent this forum would have advice on what format to create the style guide in because of their experience (although it may not directly relate to their main daily objectives.) Maybe the actual exporting of the information included in a style guide to some format is not the goal of the content writer, but at the end of the day the information has to be bundled up somehow. And there is no information out there about that.

If it hurts your feelings so bad that I asked this question, I’m honestly sorry. And thanks for your very helpful response.