You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a proposed structure for documentation on rom-rb.org. The content model provides a roadmap/demonstration of how to handle the long-term structure of the growing collection of content and how different topics can be represented.
Some of the names can potentially be changed around, but I think this is roughly what’s needed for 1.0.
Keep in mind that this is not about defining visual navigation on the site (though navigation should mostly be a product of the content model, there are a few contextual things that mean it’s not necessarily a 1:1 mapping). It’s also not an entire content strategy.
I haven’t addressed versioning, as I think it would be wiser to keep all docs unified around the current release state until after 1.0 has stablized and is more widely used (I am happy to elaborate on my rationale for this if people disagree—or see the notes on edge/experimental guides below).
About
High level overview of ROM, its structure, goals, and philosophy.
/about/introduction
What does ROM do? What problems does it solve? What does a ROM app look like?
/about/philosophy
Design concepts and rationale behind ROM. Features and tradeoffs. How it builds on previous ideas. Why ROM is not an ORM.
/about/glossary (/about/concepts)
Definitions of core concepts and vocabulary. All high level terms in ROM’s API should appear here (not just mappers, relations, commands, but also headers, datasets, etc). Should also include broader concepts and patterns that are relevant, like functional transformations, DCI, CQRS, etc.
/about/ecosystem
High level overview and map of the ROM ecosystem and how different projects fit into the whole. Could be included in the Community or Code sections instead.
/about/roadmap
Looking into the future. Could be included in the Community or Code sections instead.
Guides
Detailed developer reference that demonstrates how to use all the common (and not so common) features of ROM.
Basics
The basic stuff that everyone needs to know.
/guides/basics/setup (/guides/basics/registry or /guides/basics/env)
A guided tour of the setup and finalize hooks. The env registry could go here too, or could go in its own guide (same goes for setup DSL).
/guides/basics/relations
A guided tour of relations.
/guides/basics/mappers
A guided tour of mappers.
/guides/basics/commands
A guided tour of commands.
Adapters (Extensions? Plugins?)
These could also be at the top level (/guides/sql, /guides/mongo, etc).
/guides/adapters/memory
Using the memory adapter API in relations (restrict, project etc).
/guides/adapters/sql
A guided tour of rom-sql.
/guides/adapters/sql/relations
How to do various things with Sequel datasets and ROM.
/guides/adapters/sql/commands
How to do various DB specific things with commands.
/guides/adapters/sql
/guides/adapters/datamapper (/guides/adapters/dm)
A guided tour of rom-dm. Probably should mention “Datamapper 2.0” in an h1 for SEO purposes.
/guides/adapters/mongo
A guided tour of rom-mongo.
/guides/adapters/foo
etc...
Integrations (Plugins? Extensions?)
/guides/integrations/rails
Guide to all the features in ROM rails.
/guides/integrations/rails/generators
Listing of all provided generators.
/guides/integrations/rails/forms
Guided tour of ROM/Rails forms.
/guides/integrations/sinatra
How to integrate with Sinatra.
/guides/integrations/lotus
How to integrate with Lotus.
/guides/integrations/roda
How to integrate with Roda.
Advanced
Advanced and intricate stuff that is of special interest to document. @solnic to advise here.
/guides/advanced/aggregate-mapping
Stuff that is really not possible in other frameworks.
Edge (Experimental)
A place for experimental and changing features that aren’t necessarily baked into the core 1.0 API contract, but may be in future.
/guides/edge/try-either (/guides/edge/unsound)
Try/either semantics in commands. This may move into the core, but for now, it would be great to have it documented in brief (if it works!).
Internals
A guide to ROM internals and conventions. Mostly for people who want to contribute. Far less important than the guides listed above.
/guides/internals/adapters
A guide to writing adapters, repositories, datasets, using the linter, etc. (/guides/internals/linter could be its own guide as well).
Architecture/Ruby design conventions. Immutability, use of Equalizer, etc.
/guides/internals/testing
How testing works.
Tutorials (Examples, Samples)
Tutorials are written in a more conversational tone and assume less prior knowledge than guides. They’re beginner friendly, and provide step-by-step instructions for accomplishing specific things.
This could also be a subset of guides (/guides/tutorials). Or they could be pushed onto the blog (/blog/tags/tutorials).
The more I think about it, the less enthusiasm I have for tutorials. They are much more time consuming to write and maintain than guides, and they are generally only read once or twice when a reader is working through the examples, rather than referred to on an ongoing basis. If we were to name this section _Examples, we could potentially provide a mixture of short, example walkthroughs referencing GitHub repos like @gotar’s sinatra-rom project, as well as the existing tutorials described below._
/tutorials/rails-pet-store
Yes, I am literally (not figuratively) suggesting we replace the todo app with a contrived “pet store” sample domain model which harks back to the glory days of J2EE (disclaimer: not actually glory days). The “pet store” model is a subtle way of trolling Rails and DHH (but in a fun way, not a nasty way), while at the same time, provides genuinely useful examples of how to do more complex stuff like associations that the current tutorial overlooks.
/tutorials/sinatra-todo-api
A todo list API is ideal for demonstrating Sinatra.
/tutorials/adapter-from-scratch
See #51. It would be nice to work through a step by step example for connecting to a really basic data source (something like the todo.txt flat-file format which would be analogous to the existing CSV or YAML adapters, although less general purpose).
Code
Pointer to the source code and its dependencies.
/code/status
Status of projects in the ROM ecosystem and the latest release versions.
Community
All about people and communication, sharing and collaboration.
Who ROM is (we are a group of users and contributors)
The goals of the project (why we’re here)
Why contribute? (you should join in too)
How to contribute (next steps)
/community/contribute
Contributor information. Where to go and what to do. Sets high level expectations.
/community/conduct
A code of conduct. A starting point would be the Contributor Covenant which is included by default in Bundler generated Gems. See: #49
/community/press (/community/testimonials)
Good stuff that people are saying about ROM. Aspirational at this stage.
/community/events
Aspirational at this stage.
Blog
Its current use is more like a News section, but it can (and should) expand to cover various other things of interest, including use cases, links to cool stuff people are doing with ROM, mentions of edge API changes and experimental concepts, etc.
It would be a good to come up with some pre-defined main categories to use as tags, as this provides a clear template for contributions. Am open to people shooting this down as a bad idea, but I have provided some topic suggestions below.
Changelog
Consider merging the Release and Announcement tags into a single Changelog category. Alternatively, we could mix blog posts with the specific tags into a standalone Changelog page that also monitored GitHub activity. I prefer the blog approach though—simple and reflects what blogs do best.
Features
Explaining, clarifying, highlighting specific features and new capabilities in ROM. Answering common questions, and linking to docs, along with copious code snippets.
Case Studies (Examples?, Practice? In Practice?)
Stories about how ROM is being used in practice.
Events
Heads-up of upcoming talks and demos of ROM at Ruby events around the world. Also reviews or posts of slides/details from the talks.
Design (Architecture? Concepts? Articles?)
Software design articles and posts about conceptual and philosophical stuff, particularly areas where ROM is different from other libraries.
News, General
Maybe.
The text was updated successfully, but these errors were encountered:
This is a proposed structure for documentation on
rom-rb.org. The content model provides a roadmap/demonstration of how to handle the long-term structure of the growing collection of content and how different topics can be represented.Some of the names can potentially be changed around, but I think this is roughly what’s needed for 1.0.
Keep in mind that this is not about defining visual navigation on the site (though navigation should mostly be a product of the content model, there are a few contextual things that mean it’s not necessarily a 1:1 mapping). It’s also not an entire content strategy.
I haven’t addressed versioning, as I think it would be wiser to keep all docs unified around the current release state until after 1.0 has stablized and is more widely used (I am happy to elaborate on my rationale for this if people disagree—or see the notes on edge/experimental guides below).
About
High level overview of ROM, its structure, goals, and philosophy.
/about/introduction
What does ROM do? What problems does it solve? What does a ROM app look like?
/about/philosophy
Design concepts and rationale behind ROM. Features and tradeoffs. How it builds on previous ideas. Why ROM is not an ORM.
/about/glossary (/about/concepts)
Definitions of core concepts and vocabulary. All high level terms in ROM’s API should appear here (not just mappers, relations, commands, but also headers, datasets, etc). Should also include broader concepts and patterns that are relevant, like functional transformations, DCI, CQRS, etc.
/about/ecosystem
High level overview and map of the ROM ecosystem and how different projects fit into the whole. Could be included in the Community or Code sections instead.
/about/roadmap
Looking into the future. Could be included in the Community or Code sections instead.
Guides
Detailed developer reference that demonstrates how to use all the common (and not so common) features of ROM.
Basics
The basic stuff that everyone needs to know.
/guides/basics/setup (/guides/basics/registry or /guides/basics/env)
A guided tour of the setup and finalize hooks. The env registry could go here too, or could go in its own guide (same goes for setup DSL).
/guides/basics/relations
A guided tour of relations.
/guides/basics/mappers
A guided tour of mappers.
/guides/basics/commands
A guided tour of commands.
Adapters (Extensions? Plugins?)
These could also be at the top level (/guides/sql, /guides/mongo, etc).
/guides/adapters/memory
Using the memory adapter API in relations (
restrict,projectetc)./guides/adapters/sql
A guided tour of rom-sql.
/guides/adapters/sql/relations
How to do various things with Sequel datasets and ROM.
/guides/adapters/sql/commands
How to do various DB specific things with commands.
/guides/adapters/sql
/guides/adapters/datamapper (/guides/adapters/dm)
A guided tour of rom-dm. Probably should mention “Datamapper 2.0” in an h1 for SEO purposes.
/guides/adapters/mongo
A guided tour of rom-mongo.
/guides/adapters/foo
etc...
Integrations (Plugins? Extensions?)
/guides/integrations/rails
Guide to all the features in ROM rails.
/guides/integrations/rails/generators
Listing of all provided generators.
/guides/integrations/rails/forms
Guided tour of ROM/Rails forms.
/guides/integrations/sinatra
How to integrate with Sinatra.
/guides/integrations/lotus
How to integrate with Lotus.
/guides/integrations/roda
How to integrate with Roda.
Advanced
Advanced and intricate stuff that is of special interest to document. @solnic to advise here.
/guides/advanced/aggregate-mapping
Stuff that is really not possible in other frameworks.
Edge (Experimental)
A place for experimental and changing features that aren’t necessarily baked into the core 1.0 API contract, but may be in future.
/guides/edge/try-either (/guides/edge/unsound)
Try/either semantics in commands. This may move into the core, but for now, it would be great to have it documented in brief (if it works!).
Internals
A guide to ROM internals and conventions. Mostly for people who want to contribute. Far less important than the guides listed above.
/guides/internals/adapters
A guide to writing adapters, repositories, datasets, using the linter, etc. (/guides/internals/linter could be its own guide as well).
/guides/internals/processor (/guides/internals/mapper)
Transproc, processors, the
callconvention, mappers, etc./guides/internals/conventions (/guides/internals/architecture)
Architecture/Ruby design conventions. Immutability, use of
Equalizer, etc./guides/internals/testing
How testing works.
Tutorials (Examples, Samples)
Tutorials are written in a more conversational tone and assume less prior knowledge than guides. They’re beginner friendly, and provide step-by-step instructions for accomplishing specific things.
This could also be a subset of guides (/guides/tutorials). Or they could be pushed onto the blog (/blog/tags/tutorials).
The more I think about it, the less enthusiasm I have for tutorials. They are much more time consuming to write and maintain than guides, and they are generally only read once or twice when a reader is working through the examples, rather than referred to on an ongoing basis. If we were to name this section _Examples, we could potentially provide a mixture of short, example walkthroughs referencing GitHub repos like @gotar’s sinatra-rom project, as well as the existing tutorials described below._
/tutorials/rails-pet-store
Yes, I am literally (not figuratively) suggesting we replace the todo app with a contrived “pet store” sample domain model which harks back to the glory days of J2EE (disclaimer: not actually glory days). The “pet store” model is a subtle way of trolling Rails and DHH (but in a fun way, not a nasty way), while at the same time, provides genuinely useful examples of how to do more complex stuff like associations that the current tutorial overlooks.
/tutorials/sinatra-todo-api
A todo list API is ideal for demonstrating Sinatra.
/tutorials/adapter-from-scratch
See #51. It would be nice to work through a step by step example for connecting to a really basic data source (something like the todo.txt flat-file format which would be analogous to the existing CSV or YAML adapters, although less general purpose).
Code
Pointer to the source code and its dependencies.
/code/status
Status of projects in the ROM ecosystem and the latest release versions.
Community
All about people and communication, sharing and collaboration.
/community/contribute
Contributor information. Where to go and what to do. Sets high level expectations.
/community/conduct
A code of conduct. A starting point would be the Contributor Covenant which is included by default in Bundler generated Gems. See: #49
/community/press (/community/testimonials)
Good stuff that people are saying about ROM. Aspirational at this stage.
/community/events
Aspirational at this stage.
Blog
Its current use is more like a News section, but it can (and should) expand to cover various other things of interest, including use cases, links to cool stuff people are doing with ROM, mentions of edge API changes and experimental concepts, etc.
It would be a good to come up with some pre-defined main categories to use as tags, as this provides a clear template for contributions. Am open to people shooting this down as a bad idea, but I have provided some topic suggestions below.
Changelog
Consider merging the Release and Announcement tags into a single Changelog category. Alternatively, we could mix blog posts with the specific tags into a standalone Changelog page that also monitored GitHub activity. I prefer the blog approach though—simple and reflects what blogs do best.
Features
Explaining, clarifying, highlighting specific features and new capabilities in ROM. Answering common questions, and linking to docs, along with copious code snippets.
Case Studies (Examples?, Practice? In Practice?)
Stories about how ROM is being used in practice.
Events
Heads-up of upcoming talks and demos of ROM at Ruby events around the world. Also reviews or posts of slides/details from the talks.
Design (Architecture? Concepts? Articles?)
Software design articles and posts about conceptual and philosophical stuff, particularly areas where ROM is different from other libraries.
News, General
Maybe.
The text was updated successfully, but these errors were encountered: