search

ioos / vocabularies

Instructions and Guidelines for use of Controlled Vocabularies in IOOS-compliant data services
1 stars 8 forks source link

Document revisions and reorganization #7

Closed dpsnowden closed 7 years ago

dpsnowden commented 9 years ago

This document (the main README.md) needs some reorganization and attention to the flow. This section is included as a way to look through the main chunks below and think about the right organization. It is not written in stone, just a place to look at ideas. When the document is more mature this will become the Table of Contents.

General needs for the revision

  1. Check all links to see if they are syntactically correct. There are many links below that are still in the google code syntax. Update to github flavored markdown and check that they work.
  2. Update links to point to new documentation on gitub. Remove all google code links and find the right github repo to point at. This is an evolving process as not all GH repos are mature but we must stop directing people to google code.
  3. Edit for readability and flow. The language suffers from cut and past syndrome.
  4. Look for TODO items in the text below, address, and then delete.
  5. Write a good intro including a clear description of what this page tells us. For example, in the first sentence at the top of the page we claim that this is for use in IOOS compliant data services but we only ever reference SOS. We need to decide on the actual scope of the document (service agnostic? SOS only? All services?) and then be consistent throughout. If we intend to address all services but do not have the material yet then let's create an empty section and declare it a TODO item.
emiliom commented 9 years ago

@dpsnowden, I won't have time for a while to think about what you're saying here. But I did want to point out that I submitted a pull request a few days ago that does many fixes on README.md. @robragsdale, can you take a look and merge it?

dpsnowden commented 9 years ago

Your PR was merged but I had to do some manual revision of the doc. It's possible that some of your edits and some of mine were lost but at first glance I think I got 75% of both. Best I could do...

emiliom commented 9 years ago

Thanks, @dpsnowden . I see that a small fraction (25% is about right!) of the link corrections I had done didn't carry through. No big deal, and no worries.

robragsdale commented 9 years ago

@emiliom I can look through the Read.Me to correct any link corrections that did not carry over.