Add data philosophy and better explanations

_pages/data.md

@@ -0,0 +1,31 @@
+---
+title: Data Philosophy
+excerpt: Metadata standards and practices for the directory.
+layout: default
+permalink: /data
+nav_order: 20
+---
+
+This foundation directory should curate metadata rigorously organized enough for academic research, and should be easy enough to maintain and use for any open source organizers who find it valuable
+
+## Data Organization Philosophy 
+
+Data is stored per foundation as a single `asf.md` file per organization in the `_foundations` directory.  Each file is a standard Jekyll document with a leading YAML frontmatter document with structured metadata, followed by a `---` YAML document separator, followed by unstructured Markdown content.
+
+**Keep Updates Simple** Each foundation is a separate text-based document, making updates simple to make and review via GitHub PRs.
+
+**Enough Structured Data** Metadata follows a simple schema, with a goal to be "good enough" for common research cases.  Researchers needing more structured data are welcome to collaborate and add new fields or features.
+
+**Human Readable Formats** Using YAML and Markdown with GitHub Pages ensures the directory can be simple to understand for anyone, and can be a resource for anyone in open source who wants to learn about Foundations.
+
+## Schemas And Validation
+
+A simplistic [schema for foundation metadata](https://github.com/Punderthings/fossfoundation/blob/main/_data/foundations-schema.json) is checked in.  Suggestions for improvements to make the data more useful are appreciated!
+
+The [roadmap](roadmap) includes building linting and data consistency checks.  Currently, these are done manually, or via using semi-automated ruby scripts in the `assets/ruby` directory.  For example:
+
+```ruby
+# If the schema changes, partially generate the Liquid to display foundations.html
+assets/ruby/schema_utils.rb schema2liquid('_data/foundations-schema.json', ...)
+# This generates the bulk of the page, but needs to be manually dropped in
+```

_pages/index.md

@@ -6,12 +6,13 @@ permalink: /
 nav_order: 1
 ---
 
-Welcome to the FOSS Foundations Metadata directory!  We are eager to collaborate with academic researchers and open source practitioners alike on curating rich common metadata about the many excellent non-profit Foundations that either host or help open source projects.
+Welcome to the FOSS Foundations Metadata directory!  We are eager to collaborate with academic researchers and open source practitioners alike on curating rich common metadata about the many excellent non-profit Foundations that either host or help open source projects succeed.
 
-- See the current [directory of foundation metadata](listing). 
+- Discover the [directory of foundation metadata](listing). 
 - Read the [roadmap to see where we're headed](roadmap).
-- Useful [resources to learn about FOSS Foundations](resources).
-- How to [contribute to this site](CONTRIBUTING.md).
+- See the [starting philosophy around data design](data).
+- Find useful [resources to learn about FOSS Foundations](resources).
+- Learn how to [contribute to this site](https://github.com/Punderthings/fossfoundation/blob/main/CONTRIBUTING.md).
 - Be nice and respect our [Code of Conduct](CODE_OF_CONDUCT).
 - We can help you [Choose A Foundation](https://chooseafoundation.com) for your project to join.
 - Learn about your current host, [Shane Curcuru](https://shanecurcuru.org).
@@ -33,6 +34,8 @@ Welcome to the FOSS Foundations Metadata directory!  We are eager to collaborate
 
 ## Data
 
+Read more about our [data philosophy](data).
+
 - Store basic metadata in _foundations/*asf*.md frontmatter, parseable as YAML
   - Individual files makes PRs very simple and limited to the organization you're updating
   - Most data fields are purely optional, since we rely on volunteers to research data

_pages/resources.md

@@ -3,7 +3,7 @@ title: Resources
 excerpt: Overviews and helpful links about open source governance and foundations.
 layout: default
 permalink: /resources
-nav_order: 20
+nav_order: 30
 ---
 
 Want to understand more about open source projects, governance, and foundations?  We've picked out some of the best places out there to learn from.  As with most of open source, we're building on the work of many, many other excellent contributors out there.

_pages/roadmap.md

@@ -23,7 +23,7 @@ This site is meant to be high-level resource for anyone interested in FOSS proje
 require 'yaml'
 require 'open-uri'
 # Future plans: have more stable programmatic URL and listing features; offer CSV and other formats
-asf = YAML.load(URI.open("https://raw.githubusercontent.com/ShaneCurcuru/fossfoundation/main/_foundations/asf.md"))
+asf = YAML.load(URI.open("https://raw.githubusercontent.com/Punderthings/fossfoundation/main/_foundations/asf.md"))
 puts asf['legalName']
 ```
 
@@ -44,4 +44,4 @@ puts asf['legalName']
 
 ## Site Governance
 
-This site is run by Shane Curcuru, with the intention of attracting contributors and other co-maintainers who are interested in helping FOSS foundations, projects who might want to come to foundations, and academic researchers alike.  The long-term plan is to build a community of equal maintainers to ensure site longevity.
+This site is run by [Shane Curcuru](https://shanecurcuru.org), with the intention of attracting contributors and other co-maintainers who are interested in helping FOSS foundations, projects who might want to come to foundations, and academic researchers alike.  The long-term plan is to build a community of equal maintainers to ensure site longevity.