String freeze: Blogapi module help text [#189870]

Copying over relevant portion of O Govinda's commentary on http://drupal.org/node/101090:

Home » Administer » Help » Blogapi

SUGGESTION:

The name for this module may make perfect sense for developers, but for others it is jargon--and jargon tends to put people off. Would you consider giving the module a friendly name? You could ask Drupal users (or the Documentation List) to suggest one, one that might make sense to someone not technically well-informed enough to know what an API is.

Also, as long as we have the present name, is it "blogapi" or "blogAPI" or "blog API"? It should be consistent.

REVISED:

The blog API module gives your users the freedom to use the blogging tools they want to add posts to their blogs on your site.

When this module is enabled and configured you can use programs like Ecto to create and publish posts. The module supports several blogging APIs that are based on XML-RPC, such as the Blogger API, the MetaWeblog API, and most of the Movable Type API. Any desktop blogging tools or other services that support these APIs (Flickr's "post to blog," for example) should work.

This module also allows you to specify which content types can be posted with external blogging tools. So, for instance, users can post forum topics as well as blog posts. Where supported, the external blogging tools will display each content type as a separate "blog". [MY COMMENT: "Where supported"? Where what is supported--the tools or the feature?]

For more information please read the configuration and customization handbook BlogApi page.

Blog API administration pages
Blog APIs

[MY COMMENT: I don't use the Blog API module, so I'm not closely familiar with it. I've tried to make the text as clear as I can, given my limited understanding.]
-----------------------------------------------------------------------------

Comment	File	Size	Author
#8	blogapi_helptext_5.patch	8.1 KB	keith.smith
#8
#6	blogapi_helptext_4.patch	8.18 KB	catch
#6
#5	blogapi_helptext_3.patch	8.18 KB	keith.smith
#5
#2	blogapi_helptext_2.patch	5.83 KB	keith.smith
#2
#1	blogapi_helptext.patch	5.8 KB	keith.smith
#1

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

keith.smith CreditAttribution: keith.smith commented 6 November 2007 at 21:35

Status:

Active

» Needs review

File	Size
blogapi_helptext.patch	5.8 KB

Patch attached.

Note that the url for Ecto has apparently changed since this help text was originally created.

Comment #2

keith.smith CreditAttribution: keith.smith commented 6 November 2007 at 23:57

File	Size
blogapi_helptext_2.patch	5.83 KB

I went to go work on another patch, and realized that I was inconsistent in my use of url() between it and this.

New patch attached.

Comment #3

mauror CreditAttribution: mauror commented 7 November 2007 at 02:07

Status:

Needs review

» Reviewed & tested by the community

The patches applies, coder module does not complain, only changes are in the help text, the links are valid, I wonder if this should be ready to be commited?

Please tell me if I did something outrageous by changing status...

Comment #4

Gábor Hojtsy

he/him

Hungarian

Hungary

CreditAttribution: Gábor Hojtsy commented 7 November 2007 at 09:45

Status:

Reviewed & tested by the community

» Needs work

Issues I found:

- MacOSX is Mac OS X
- BlogApi is Blog API (to be consistent at least)
- the bigger help text should mention that the different content types appear as different blogs *in the client application*, and should include the "if supported" clause
- the Blog APIs menu item should also be retitled with the now uncovered fact that there is no engine setting anymore (so the plural title does not make sense).

Otherwise this seems to be a much more user centric help text then before, it does not speak about the API that much, but tells more about the clients.

Comment #5

keith.smith CreditAttribution: keith.smith commented 7 November 2007 at 15:17

Status:

Needs work

» Needs review

File	Size
blogapi_helptext_3.patch	8.18 KB

Thanks for the comments!

- I fixed MacOSX to be Mac OS X. Sorry about that.
- I fixed the instances of BlogApi I found, namely in the handbook page link.
- The content-types-as-separate-blog stuff should be consistent now, and includes a "if supported and available".
- I retitled the menu item (removing the plural), and futzed with the form description.
- I incidentally renamed some "weblogs" to "blogs", for consistency. We actually use "weblog" in a few other places (ping, aggregator), but not nearly as often as we use blog. I can easily change this back if it bothers anyone.

You mention in #4

Otherwise this seems to be a much more user centric help text then before, it does not speak about the API that much, but tells more about the clients.

Er. This is a good thing, right? If it should slant in some other direction I'll happily try to adjust it.

Comment #6

catch

he/him

English

CreditAttribution: catch commented 7 November 2007 at 15:29

File	Size
blogapi_helptext_4.patch	8.18 KB

Strings look much better to me (as usual). Attached patch fixes two code style issues I found - double quotes where the ' had been removed from the string changed to single quotes, and added double quotes for a different string where \' was being used to avoid the escaping.