Copyedits

[allanaaa]

First pass.

Notes:

• I'm working on standardizing headers in terms of Title Cases. Some things that are just bold (e.g. Feature List headings) are being taken down to Sentence case. I think H2 through H4 can also come down to Sentence case (Questions to ask while planning; Try Omeka Classic before installing) but haven't inputted it yet.
• Standardizing when things have periods at the end (paragraph yes, title no, last item of list yes, items of lists if they are complete sentences yes). Still deciding on when to use colons (e.g. "Scholars:").
• Moved the "How to spot an Omeka site" down in the "Examples" page. I might even put it further down, after the teaching section.
• Used cached versions of those links.
• Technically, 508 is a section of the "Rehabilitation Act" not the ADA? News to me.
• There is a Classic_vs_Net.md page in the GettingStarted/ folder that appears not to be linked anywhere. Should it be deleted, or added to the nav? Will fix #29 .
• There is a MkDocs video plugin we can add that will allow us to embed our screencasts (or some of them at least) on the Screencasts page and throughout the docs. Could make those videos more used.
• Did some misc clarification and specification of language used. Minor testing like "Does the exhibits dropdown in the advanced search show only public exhibits" and etc.?
• I am biased but I prefer the term "database" or "collections" or etc. instead of "archive" wherever it's used to refer to items added. Fixes #43 .

[allanaaa]

Oh yeah, and jury's still out on whether you should capitalize "boolean."

[allanaaa]

Fixes #32 now too.

[allanaaa]

A recap of the major stuff:

• Two pages deleted: Plugins/ZoomIt and Plugins/Shortcodes
• Two code bits added: attributes (to make links open in new tabs) and admonitions (to make cute warning boxes like https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage)
• Some images deleted and some downsized. One new image.
• Colours changed, including links to red, code snippets to black, and sidebar to slightly higher contrast.
• Main div width changed to 1400px (still up for debate).
• Links now underline in the style of the Omeka S docs.
• Adding title text alongside alt text to many images (more to come in the future).
• Made sure very plugin page now links to its download page on the website.
• Some stylistic stuff like changing headings, use of bold and italics, bullet lists, etc (more to come, still deciding on style guide rules).
• A bit of added text here and there where something read weird and needed clarifying.
• Everything else is link fixes, language tightening, and some updated image alt text.

More detailed notes with each commit.

The easiest way to see it all is to skim the changes https://github.com/omeka/classic-enduser/pull/44/files and see if anything jumps out at you for review.

I did some testing to verify some of the early pages, stuff in Content and Admin, so if there are meaningful language changes to check up on, they'll be there. I didn't do any technical stuff on the plugins page or after, so those can be skimmed quickly.

[sharonmleon]

Re: Database vs. collections vs. archive. As much as possible we would like to eliminate the use of the word archive. Generally I like collection, but that can be confusing in the context of Omeka Classic where Collections are a feature. As a result, I tend to default to repository of items.

[sharonmleon]

Question about the specifying the colors of the elements of the interface in the narrative documentation: does this create accessibility confusion based on the perception of the color names? I.e. does teal mean too many different things to too many different people?

[sharonmleon]

On the styling for feature lists, etc.: In some cases you’ve converted colons to periods, but not all (see Admin General Settings). So changing

• Feature: Definition

To

• Feature. Definition

We have tended to use the colon, but I’m happy to go with the change if it’s consistent

[sharonmleon]

I think that we're okay with the redundancy in the Item Type Element Set documentation because the edit interface does engages both in the left hand navigation and in the General Settings section.

[allanaaa]

I.e. does teal mean too many different things to too many different people?

Fair question. The original alt text referred to a red arrow, which I suppose was from a previous image version, so I just updated it. I don't find the teal arrows very visible either. Might be best to redo some of the image annotations in higher contrast and redo the alt text again. (I assume teal was chosen from the branding colours....)

[allanaaa]

On the styling for feature lists, etc.: In some cases you’ve converted colons to periods, but not all (see Admin General Settings). So changing

* **Feature:** Definition

To

* **Feature.** Definition

We have tended to use the colon, but I’m happy to go with the change if it’s consistent

Yeah, I am still bouncing around some of these style-guide-y questions. When to use bold and italic, whether an "Interface Button" is different from an Interface link vs. a url/path and what the dropdown options are, etc. etc. I mostly stopped in the interests of time, so these'll go into a future update when we do more substantive changes.

[allanaaa]

Perhaps something here about how the thumbnail and full sized service images have size settings in the general appearance settings.

I can't see what this refers to. Can you tell me the page you were on? Or I can make a note to cover it in the next update.

[allanaaa]

Here I think we can eliminate that use of "archive" for something more general like "your digital objects" or "your materials."

Same for this comment - there are quite a few mentions left, not sure which one in particular this refers to, but I've made a note to be more comprehensive on the next pass, unless you'd rather I zap them all now.

[zerocrates]

Those "here" comments from Sharon look like they're supposed to be line comments on the diff... Github can see that they're "reviews" but isn't showing what lines they go with for some reason.

[sharonmleon]

That's super annoying. I'm working in the Github app which appears to let me comment on individual line diffs, as John suggests. I'll have to figure out some other way to do this.

[sharonmleon]

If it helps, for me they show up attached to the lines when you look at the list of file changes....

[allanaaa]

If it helps, for me they show up attached to the lines when you look at the list of file changes....

I figured it must have been something like that. If you want to just write in some extra details manually about what files & lines, I can hunt them down and we can figure out the app-to-website issue later.

[sharonmleon]

I'll circle back after I review some other stuff and make a list of the files and lines.

[allanaaa]

Looks great, thanks! I'll get on these ASAP. Could you also merge #42 if you're happy with it for now?

[sharonmleon]

I haven't looked at that one yet, but I'll get there ASAP.

[allanaaa]

@sharonmleon @zerocrates Anything else to add to or remove from this PR before it gets merged? The only outstanding is whether you want me to do a sweep to remove contractions.

[sharonmleon]

No worries on the contractions.