Background:
This issue is part of the task to update/create the hook_help texts of the modules for Drupal 8:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
- write the hook_help function
- review d.o. docs at https://drupal.org/documentation/modules/serialization

Files: 
CommentFileSizeAuthor
#26 Screen Shot 2013-10-16 at 17.19.42.png53.59 KBdamiankloip
#21 2036689-16-serialization-help-21.patch1.73 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,220 pass(es).
[ View ]
#18 2036689-16-serialization-help-18.patch1.72 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,892 pass(es).
[ View ]
#16 2036689-16-serialization-help.patch1.63 KBlinclark
PASSED: [[SimpleTest]]: [MySQL] 58,545 pass(es).
[ View ]
#13 create-help-text-serialization-2036689-11.patch1.5 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,558 pass(es).
[ View ]
#7 create-help-text-serialization-2036689-6.patch1.52 KBbabruix
PASSED: [[SimpleTest]]: [MySQL] 58,672 pass(es).
[ View ]
#1 create-help-text-serialization-2036689-1.patch1.1 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 57,300 pass(es).
[ View ]

Comments

StatusFileSize
new1.1 KB
PASSED: [[SimpleTest]]: [MySQL] 57,300 pass(es).
[ View ]

First attempt. Again, I'm not sure what this module is about so text is a bit nonesense, but I'm hoping to improve with the feedback.

Component:documentation» serialization.module
Priority:Normal» Critical

Since hook_help() is required by the Documentation Gate and this module has none, this is a critical issue. Let's move it over to the Serialization module component for the moment, and get feedback on the proposed text's accuracy from the module maintainers.

Status:Active» Needs review

+++ b/core/modules/serialization/serialization.moduleundefined
@@ -1 +1,14 @@
+      $output .= '<p>' . t('The Serialization module provides a service for serializing and deserializing data to/from formats such as JSON and XML. Serialization is the process of translating data structures or object state into a format that can be stored (for example, in a file) and resurrected later. For more information, see the <a href="@doc_url">online documentation for the Serialization module</a>.', array('@doc_url' => 'https://drupal.org/documentation/modules/serialization', '@serialization_url' => 'http://stateless.co/serialization_specification.html')) . '</p>'; ¶

I'm not too keen on using words like 'translation' here as we're not really translating things. I think it might be a good idea to split this help up further in to different sections (see taxonomy_help() for exmaple). The serializer bascally has:
- Normalizers/Denormalizers to get data to/from a normalized array
- Encoders/Decoders, that convert the serialized data from/to the normalized data.

Oh, hope that makes sense :) Lin will probably have some better ideas on this, docs and decent wording is not my thing....

Status:Needs review» Needs work

Assigned:Unassigned» babruix
Issue tags:+prague 2013

Status:Needs work» Needs review
Issue tags:-prague 2013
StatusFileSize
new1.52 KB
PASSED: [[SimpleTest]]: [MySQL] 58,672 pass(es).
[ View ]

Updated patch.

"Serialization is the process of interpretation of data structures or object state into a format that can be stored (for example in a file) and resurrected later."

I don't think "interpretation" is the right word here. Interpretation means "The action of explaining the meaning of something" and I don't think any explaining goes on here! How about "converting" - Convert: Cause to change in form, character, or function.

"Serialization is the process of converting data structures or object states into a format ..."

might be better?

How about this:

Serialization is the process of converting data structures like arrays and objects into a string. This allows the data to be represented in a way that is easy to exchange and store (e.g. for transmission over the Internet or for storage in a local file system). These representations can then be deserialized to get back to the original data structures.

#9 - yes, let's go with that, thanks! One thing: after "e.g.", you need a comma.

Patch:

- incorporates #9 & #10
- simplifies markup. I removed the definition list. It is simpeler like this (also for translators) and more in line with the about section of all other hook help texts

See, I knew Lin would be a good candidate for this! :)

StatusFileSize
new1.5 KB
PASSED: [[SimpleTest]]: [MySQL] 58,558 pass(es).
[ View ]

I mean this patch of course

Assigned:babruix» Unassigned

unassign

Looks good to me! The third paragraph doesn't end in "." but I didn't see anything else wrong.

Well, one other thing. In modules that have a UI, we should have a Uses section explaining how to use it. In modules that don't, we've generally had something like:

This module does not have a user interface. It provides blah blah blah for other modules to use.

or something similar. It seems like we might want to say here who/what would use this service -- are there particular Core or Contrib modules?

StatusFileSize
new1.63 KB
PASSED: [[SimpleTest]]: [MySQL] 58,545 pass(es).
[ View ]

Ha, thanks Damian :)

I have added a paragraph to explain that this does not have a UI and what modules would use it.

I have also adjusted the paragraph about normalizers and encoders.

Status:Needs review» Needs work

Looks good! Very clear.

The only addition I would make is that when you say "such as REST", you link that to the REST module help page (which is our convention in other hook_help() when referring to another module).

After that is done, someone will need to manually test this to make sure the formatting and links are OK. So if someone adds this to the patch, please add a "needs manual testing" tag and set to "needs review" status. Thanks!

Status:Needs work» Needs review
Issue tags:+Needs manual testing
StatusFileSize
new1.72 KB
PASSED: [[SimpleTest]]: [MySQL] 58,892 pass(es).
[ View ]

This patch adds the link to help of the rest modules, which does not exist yet. So that is a broken link.

The formatting looks okay and the link to d.o. is correct.

In another issue it was stated that "e.g." should be avoided because translators may not understand the abbreviation - so use "for example" in full.

Status:Needs review» Needs work

Yes, that is a good idea. I think the rest of the patch is fine. Thanks!

StatusFileSize
new1.73 KB
PASSED: [[SimpleTest]]: [MySQL] 59,220 pass(es).
[ View ]

Patch changes e.g. in "for example"

Status:Needs work» Needs review

setting status

The last submitted patch, 2036689-16-serialization-help-21.patch, failed testing.

Status:Needs work» Needs review
Issue tags:+Needs manual testing

Thanks! I think this is looking good.

Can someone give this patch a manual test to make sure the formatting is OK and the links work?

Status:Needs review» Reviewed & tested by the community
Issue tags:-Needs manual testing
StatusFileSize
new53.59 KB

Just read through, applied, took screenshot. The formatting looks a-ok to me :)

Screen Shot 2013-10-16 at 17.19.42.png

Status:Reviewed & tested by the community» Fixed

Committed cb9ab9a and pushed to 8.x. Thanks!

Status:Fixed» Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.