Future of IOOSTech at code.google.com

[Derrick Snowden - NOAA Federal]

Hi all,

Several years ago we began using the ioostech google code wiki/repository/issue tracker to organize the effort to create the SOS milestone 1.0 templates.  Since then, the issue tracker remains in use but the wiki is no longer curated or growing.  We've also begun using Github across most RAs and for the IOOS PO efforts as well (github.com/ioos/).  I think this shift toward Github will only continue calling in to question the wisdom of keeping the IOOSTech site alive.  As it is, it misrepresents our efforts because it isn't well curated.  The SOS guidelines page has been superseded by a Word document called the Web Service Description Document.  Yet, many of us still refer to the outdated IOOSTech wiki because it is easier to create a URL link to a specific section of a wiki than it is to reference something buried deep inside a document.  So, I'm willing to accept that the Word document may not have been well thought out and I'm proposing a new Github based structure for all of the so called IOOS policies, protocols, standards etc.  I'm writing to get your input before we completely implement it in case you can help me prevent a mis-step like the Word Doc.  Here's the idea in summary.

I will lock down the privileges a little tighter to encourage better Github style developement (i.e. fork==>modify==>pull request).

1. The high level directory or table of contents lives at ioos.github.io.  For the most part this will be a static landing page summarizing DMAC which contains links to the individual documents/web pages etc.

2. Each major topic area that is sufficiently stand alone will be developed as a single repo.  No more wiki's that grow without bound.

3. For repos dedicated primarily to documentation, the docs will be version controlled source files and will be managed like software code.  The format of the docs will be primarily and perhaps exclusively Markdown or reStructured Text. 

4. Wikis for each repository are still encouraged for creating or discussing ideas or for creating demos and HOWTOs but the primary documentation will be version controlled source.

5. These source files will be processed through a rendering/templating engine (Sphinx, Pelican, and/or Jekyll) which can be hosted on Github Pages. 

The first few docs that will be migrated and published are

1. The SOS milestone 1.0 Web Service Description Document AND the M1.0 SOS templates will be hosted at github.com/ioos/sos-guidelines.  All Issues from IOOSTech that are still outstanding will also be moved.  The Github Pages URL then will become ioos.github.io/sos-guidelines.  The Markdown file which was translated from the Word doc is currently in draft at https://github.com/abirger/Docs/blob/master/SOS_WSDD_github.md  (Yes, Alex actually converted a Word doc to markdown by hand. Please don't start referencing this yet.)

2. The IOOS CSV TSV document will be hosted at github.com/ioos/ioos-tsv-csv (or similar)

3. IOOS Observing Asset Idenitifiers (name??)

4. IOOS Vocabulary guidelines.

Now is your chance to chime in on this idea.  With the new FFO being drafted this year we badly need an effort to clarify our documentation.  I want to get this right so that we can all get behind it .  Please let me know if you see any pitfalls or other gotchas.  I'm especially concerned with the SOS Templates and the supporting documentation and issue tracker. 

Thanks,

Derrick

--

Derrick Snowden
System Architect and Acting Chief, Operations and Communications Division
US IOOS
1100 Wayne Ave, Suite 1225
Silver Spring, MD 20912
+1 301 427 2464 (o), +1 301 427 2073 (f)

Find us on Facebook

[Shane StClair]

A few weeks late, but I totally support this. Moving everything to GitHub will make things easier to find, give us access to better tools, encourage accessible, plain text formats, and provide a chance to eliminate some of the clutter that's built up on other resources (ioostech wiki). +1

-Shane

--
--
You received this message because you are subscribed to the Google
Groups "ioostech_dev" group.
To post to this group, send email to iooste...@googlegroups.com
To unsubscribe from this group, send email to
ioostech_dev...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/ioostech_dev?hl=en

---
You received this message because you are subscribed to the Google Groups "ioostech_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ioostech_dev...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
Shane StClair
Software Engineer
Axiom Consulting & Design
http://www.axiomalaska.com