Minor issue: What is the "correct" Dev Guide title?

[jvroig]

Howdy.

When writing a dev guide (for a product, API, language, database, framework, etc), what's the most "correct" way to name it?

For example, if the product is XYZ, is it:
1. The XYZ Developer's Guide
2. The XYZ Developers' Guide
3. The XYZ Developer Guide
4. The XYZ Developers Guide

I've seen examples of almost all the titles above, and I'm not sure what the "right" naming should be. I went through some grammatical scenarios like "well, if it means 'The XYZ Guide for Developers', then that's not actually a possessive form, therefore the apostrophe has no place there...", but then again, don't we usually use the possessive form for stuff like "Administrator's Bible" for similar docs? Then, there's also the issue of plurality - even if we decide that there should be no apostrophe, is it properly a "Developers Guide" or a "Developer Guide"?

I know, it's really a minor, insignificant issue, but if there is such a thing as the "Right Way (TM)" to name the document, I'd rather know it and stick to it than possibly get it wrong and face the scorn of my grammatically-superior peers and/or judges for producing documentation that is otherwise technically accurate but the title is in woeful need of a grammar reboot

Thanks in advance.

 

[Jaydip]

They all can be used but personally I will stick with 4. The XYZ Developers Guide like this
http://www.amazon.com/Oracle-Busines...velopers+guide

 

[jvroig]

Thanks Jaydip!

Indeed, some Oracle docs were my basis for "Developers Guide", but they are rather inconsistent. The Admin Guide, for example, is called "Oracle Database Administrator's Guide, 11g Release 2".

Other noteworthy names use different styles, such as Mozilla using the singular "Developer Guide" such as here: https://developer.mozilla.org/en-US/docs/Developer_Guide

Still others like Python and Google use "Developer's Guide" (singular + possessive):
http://developer.chrome.com/extensions/devguide.html
http://docs.python.org/devguide/

I guess I'm just thinking there has to be a "One-True-Dev-Guide-Naming-Convention" there, and it bugs me when I write "Developer's Guide" or whatever other style, because it always triggers my internal grammar-check-argue-mode (stupid brain) and I'm unsure if I'm following an erroneous practice.

I suppose it's more important that all company docs should follow the same style to be consistent, picking and sticking to just one style, be it possessive or not, plural or singular. I'm just afraid of prescribing the style to be used, which will no doubt become the standard forever and ever in the company, and then later on find out that what I prescribed (based on whatever X popular company) is actually somewhat grammatically less-accurate than another option. That would be somewhat embarrassing, even though I could just shrug and say "hey, it's not the title, it's the technical content that matters".

 

[Jaydip]

Thanks Jaydip!

Indeed, some Oracle docs were my basis for "Developers Guide", but they are rather inconsistent. The Admin Guide, for example, is called "Oracle Database Administrator's Guide, 11g Release 2".

Other noteworthy names use different styles, such as Mozilla using the singular "Developer Guide" such as here: https://developer.mozilla.org/en-US/docs/Developer_Guide

Still others like Python and Google use "Developer's Guide" (singular + possessive):
http://developer.chrome.com/extensions/devguide.html
http://docs.python.org/devguide/

I guess I'm just thinking there has to be a "One-True-Dev-Guide-Naming-Convention" there, and it bugs me when I write "Developer's Guide" or whatever other style, because it always triggers my internal grammar-check-argue-mode (stupid brain) and I'm unsure if I'm following an erroneous practice.

I suppose it's more important that all company docs should follow the same style to be consistent, picking and sticking to just one style, be it possessive or not, plural or singular. I'm just afraid of prescribing the style to be used, which will no doubt become the standard forever and ever in the company, and then later on find out that what I prescribed (based on whatever X popular company) is actually somewhat grammatically less-accurate than another option. That would be somewhat embarrassing, even though I could just shrug and say "hey, it's not the title, it's the technical content that matters".

You see it is called "Oracle Database Administrator's Guide, 11g Release 2" because there are not many database admins compared to developers :biggrin:

 

[jvroig]

Haha, witty retort, sir, +1 internet cookie :thumbsup:

 

[tfinch2]

My company uses "Programming Guide".

 

[jvroig]

Hmmm... interesting. I suppose one could sidestep this minor issue entirely by a good rewording such as what your company uses.

[Developer's / Developers' / Developer / Developers] Guide could become "Development Guide".

[Administrator's / Administrators' / Administrator / Administrators] Guide could become "Administration Guide".

And so on. Essentially, making it about a task/action instead of a person/occupation/role.

Thanks for the tip :thumbsup:

 

[DaveSimmons]

I prefer the task version. API / SDK = programming / development not programmer / developer. The person using the library or tool might be a "programmer" or "developer" or whatever other titles their company uses.