Update test module interface documentation #1325
Conversation
mattias-p
force-pushed
the
test-module-interface
branch
3 times, most recently
from
37d4f14
to
1cf36f6
Compare
mattias-p
force-pushed
the
test-module-interface
branch
from
1cf36f6
to
80d7332
Compare
|
@matsduf @marc-vanderwal @tgreenx Please review. I've rebased this on top of latest develop. |
| @@ -11,41 +13,17 @@ All translation files live in the F<share> directory in the | |||
| L<Zonemaster::Engine> source directory and all commands described here are | |||
| executed from that directory. | |||
|
|
|||
| =head2 For translators | |||
| =head1 FOR TRANSLATORS | |||
There was a problem hiding this comment.
The file name is "Localization" but it is only about translation.
| Perl to read the code and verify that it correctly implements the corresponding | ||
| Test Case specifications. | ||
|
|
||
| =head2 Internationalization |
There was a problem hiding this comment.
It is not about internationalization. It is related to translation, but mostly about the mechanism where a tag is replaced by human language, humanization?
There was a problem hiding this comment.
“Internationalization” is the industry-standard term for the process of modifying software so as to make it adaptable to different languages and customs (e.g. right-to-left scripts, formatting of numbers, etc.). The use of message tags instead of hard-coded messages in English is the way Zonemaster implements internationalization.
|
|
||
| =item | ||
|
|
||
| The zone object it's given has a parent. |
There was a problem hiding this comment.
Not necessarily. The root zone has no parent. And a undelegated zone can be tested even if it is not possible to determine its parent-to-be.
|
|
||
| =item | ||
|
|
||
| The zone object it's given has glue records. |
There was a problem hiding this comment.
Not necessarily. But if not testing will fail at Basic02.
Co-authored-by: tgreenx <96772376+tgreenx@users.noreply.github.com>
|
Regarding "internationalization" and "localization", I didn't make this up. It's actually well established terminology in the industry. See https://en.wikipedia.org/wiki/Internationalization_and_localization. Regarding the "Make few assumptions" section, I didn't make this up either. It is what our current documentation says. I simply moved it to a better place. It's good that you spotted these flaws in our documentation but I feel they're out of scope for this PR. |
|
Even if "internationalization" and "localization" are established terms the documentation could be less confusing if it concretely explains what it is all about. |
|
@matsduf I believe the documentation is quite concrete already. It explains what translators and developers need to do and what they need to think about, and I believe we have a decent linking structure that directs people to the right places. I'll add a link to the Wikipedia page. Would that be enough or do you have anything else in mind? |
| @@ -19,6 +17,7 @@ lib/Zonemaster/Engine/ASNLookup.pm | |||
| lib/Zonemaster/Engine/Constants.pm | |||
| lib/Zonemaster/Engine/DNSName.pm | |||
| lib/Zonemaster/Engine/Exception.pm | |||
| lib/Zonemaster/Engine/Localization.pod | |||
There was a problem hiding this comment.
Translation.pod was a better file name.
|
|
||
| =head2 Introduction | ||
| Zonemaster::Engine::Localization - On L<localization|https://en.wikipedia.org/wiki/Internationalization_and_localization>. |
There was a problem hiding this comment.
What should the users use the link for?
The text is about translation. What is the problem to call it "Translation"?
Purpose
I started out making this update because I felt we need a good and up to date definition of the test module interface.
Context
Having a clear definition of the test module interface will be useful when we design the custom test module feature and in turn when people make use of it.
Changes
The justification for this PR is the added and updated details. While this PR contains some amount of new details most of the diff comes from formatting and editing and moving things around. Some older language and terminology is also updated to be more precise and contemporary. I may have got a little carried away but I believe the end result is good.
How to test this PR
N/A