[Development] Spelling of module names in documentation

Robin Burchell robin+qt at viroteck.net
Wed Dec 14 16:03:15 CET 2011


Hi Henry,

On Wed, Dec 14, 2011 at 3:54 PM,  <henry.haverinen at nokia.com> wrote:
> Did you omit the mailing list by accident? I think this question might be interesting to others too, so do you mind if I post this on the list?

Yeah. I'm having a really terrible year for email...

>> if the includes, the headers, and the namespace (basically all the
>> code) are supposed to use one style, does it really make sense to make an
>> exception for the header part of the docs, when the rest (class names,
>> namespaces, etc ...) is going to be different anyway? if the point is to
>> introduce consistency, wouldn't it be better to just pick one style and stick
>> with it?
>>
>> (not that I care about this really, it's capitalisation after all, i'm just wondering
>> about the reasoning)
>
> We were considering overview articles, whitepapers, marketing materials, books and other plain English texts, which could be more readable and approachable if you can write sentences like "The Qt Service Framework allows applications to discover and invoke in-process and out-of-process services", or "The main use cases of the Qt XML Patterns module are X, Y and Z", or "the key benefits of the Qt 5.1 release include several new HTML5 features in Qt WebKit and better rendering performance with Qt Quick".
>
> In this context, the names of the tools and modules should be, well, readable English names rather than source code style names like QtServiceFramework. These module names would also be more consistent with the convention spelling of tool names like Qt Creator, Qt Designer, which are used in texts, not code.

OK. That makes more sense. I still think that reading the docs for the
"Qt XML Module" and seeing QXml* used throughout the code would be a
bit perplexing, but like I said, it's not really a big issue for me -
so I'm happy either way now I know the reasoning :)



More information about the Development mailing list