Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
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
Comment | File | Size | Author |
---|---|---|---|
#26 | Screen Shot 2013-10-16 at 17.19.42.png | 53.59 KB | damiankloip |
#21 | 2036689-16-serialization-help-21.patch | 1.73 KB | batigolix |
#18 | 2036689-16-serialization-help-18.patch | 1.72 KB | batigolix |
#16 | 2036689-16-serialization-help.patch | 1.63 KB | linclark |
#13 | create-help-text-serialization-2036689-11.patch | 1.5 KB | batigolix |
Comments
Comment #1
batigolixFirst 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.
Comment #2
jhodgdonSince 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.
Comment #3
benjy CreditAttribution: benjy commentedComment #4
damiankloip CreditAttribution: damiankloip commentedI'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....
Comment #5
jhodgdonComment #6
babruix CreditAttribution: babruix commentedComment #7
babruix CreditAttribution: babruix commentedUpdated patch.
Comment #8
StuartJNCC CreditAttribution: StuartJNCC commented"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?
Comment #9
linclark CreditAttribution: linclark commentedHow 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.
Comment #10
jhodgdon#9 - yes, let's go with that, thanks! One thing: after "e.g.", you need a comma.
Comment #11
batigolixPatch:
- 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
Comment #12
damiankloip CreditAttribution: damiankloip commentedSee, I knew Lin would be a good candidate for this! :)
Comment #13
batigolixI mean this patch of course
Comment #14
batigolixunassign
Comment #15
jhodgdonLooks 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?
Comment #16
linclark CreditAttribution: linclark commentedHa, 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.
Comment #17
jhodgdonLooks 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!
Comment #18
batigolixThis 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.
Comment #19
StuartJNCC CreditAttribution: StuartJNCC commentedIn another issue it was stated that "e.g." should be avoided because translators may not understand the abbreviation - so use "for example" in full.
Comment #20
jhodgdonYes, that is a good idea. I think the rest of the patch is fine. Thanks!
Comment #21
batigolixPatch changes e.g. in "for example"
Comment #22
batigolixsetting status
Comment #24
lostkangaroo CreditAttribution: lostkangaroo commented#21: 2036689-16-serialization-help-21.patch queued for re-testing.
Comment #25
jhodgdonThanks! 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?
Comment #26
damiankloip CreditAttribution: damiankloip commentedJust read through, applied, took screenshot. The formatting looks a-ok to me :)
Comment #27
alexpottCommitted cb9ab9a and pushed to 8.x. Thanks!