Support from Acquia helps fund testing for Drupal Acquia logo

Comments

batigolix’s picture

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.

jhodgdon’s picture

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.

benjy’s picture

Status: Active » Needs review
damiankloip’s picture

+++ 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....

jhodgdon’s picture

Status: Needs review » Needs work
babruix’s picture

Assigned: Unassigned » babruix
Issue tags: +prague 2013
babruix’s picture

Status: Needs work » Needs review
Issue tags: -prague 2013
FileSize
1.52 KB

Updated patch.

StuartJNCC’s picture

"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?

linclark’s picture

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.

jhodgdon’s picture

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

batigolix’s picture

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

damiankloip’s picture

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

batigolix’s picture

I mean this patch of course

batigolix’s picture

Assigned: babruix » Unassigned

unassign

jhodgdon’s picture

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?

linclark’s picture

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.

jhodgdon’s picture

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!

batigolix’s picture

Status: Needs work » Needs review
Issue tags: +Needs manual testing
FileSize
1.72 KB

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.

StuartJNCC’s picture

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.

jhodgdon’s picture

Status: Needs review » Needs work

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

batigolix’s picture

Patch changes e.g. in "for example"

batigolix’s picture

Status: Needs work » Needs review

setting status

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

lostkangaroo’s picture

Status: Needs work » Needs review
Issue tags: +Needs manual testing
jhodgdon’s picture

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?

damiankloip’s picture

Status: Needs review » Reviewed & tested by the community
Issue tags: -Needs manual testing
FileSize
53.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

alexpott’s picture

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.