As announced in the issue about merging 3 different glossaries on Drupal.org (http://drupal.org/node/1001316), we now face the task of reviewing the remaining one glossary (http://drupal.org/node/937).

Some of the errors in the current version:
* typo's (most of them mine)
* inconsistent style
* inconsistent explanation of acronyms
* clumsy links ("now click here on this link to read more about this topic")
* redundant information
* missing information
* html validation errors
* et cetera

This issue serves to discuss the review process

If anyone knows information on how to do a professional glossary, please drop a link ...

Comments

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

concerning the title and introduction sentences of each glossary item: in the current version (http://drupal.org/glossary) they are all different. e.g.:

book
A book is a set of book pages ...

breadcrumb(s)
is a term borrowed from "Hansel and Gretel" ....

my proposal is to standardize them all to:

lorem
A lorem is a ipsum with a dolor sit amat ....

lisarex’s picture

lisarex commented

Thanks for kicking this off. The easiest thing would be to run it through Total Validator as it'll find the broken links and other validation errors.

The primary content style guide is http://drupal.org/node/338208. Agree that capitalizing the first letter would be great.

In the previous issue, we also agreed to remove non-Drupal-specific stuff. So UX, URL etc could come out.

At some point when we're happy with the cleanup, we can ask folks to add in missing ones.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

Sorry for not using the mentioned validator. I dont want to install it on my pc. I used w3c validator instead:
http://validator.w3.org/check?uri=http%3A%2F%2Fdrupal.org%2Fglossary&cha...
I think I fixed all validation errors. Send me the report in case there is still problems

I applied proper capitalization:
http://drupal.org/node/937/revisions/view/1500664/1500678

(but i just read that it is recommended to have definition terms uncapitalized ... )

And I applied consistent definition terms and description intro's.:
http://drupal.org/node/937/revisions/view/1500678/1500788

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

The entries from the original version of the glossary are followed by a hash symbol containing a link to itself.

Anyone knows what the point of this is and whether it must be applied to all entries?

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

@lisarex: concerning URL & UX: i think they serve a purpose because they partially explain "real" drupal concepts, such as e.g. "path", "clean url" or "d7ux" (latter not in the glossary btw)

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

there is an issue here #1114198: Glossary is missing Drupal-specific terms for reporting missing terms

lisarex’s picture

lisarex commented
Status: Active » Needs work

Sorry batigolix, I wasn't clear. It's fine if the term is uncapitalized, but the definition should have a caps (I was agreeing with you in comment #1)

I ran it thru total validator. There's some letters at the top that don't have matching definitions, so I've removed those.

It also doesn't like the # that appear next to the terms:
"E898 [WCAG v2 2.4.4 (A)] Different links that use the same link text may be confusing: See matching tag(s) on line(s):"

Echoing batigolix, What are those for? Are they necessary? :)

arianek’s picture

arianek commented

heya - so, i think what the #'s are for is that they're anchor links that are linked to in a way so that people can easily copy and paste a link to someone else so they land at the definition on the page without having to scroll. they might not be compliant, but i think they are pretty handy, no?

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Status: Needs work » Needs review

i feel im done reviewing the glossary.

see http://drupal.org/node/937/revisions for a list of changes

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Assigned: batigolix » Unassigned

@lisarex / @arianek:

i moved the remaining comment on http://drupal.org/glossary in the issue concerning this topic http://drupal.org/node/1114198#comment-4565646

please remove the comment from http://drupal.org/glossary and close the comment option

arianek’s picture

arianek commented

great thanks - i've deleted the comment

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

one can still add comments to http://drupal.org/glossary

shouldnt we close these where possible?

arianek’s picture

arianek commented

not yet... there's an issue for that though! #810508: Kill handbook comments

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Status: Needs review » Closed (fixed)

closed this issue.

For reporting missing Drupal-specific terms use #1114198: Glossary is missing Drupal-specific terms