Mohit Sindhwani wrote:
Hi, I have a design question that I'd like to get some inputs on.
Note that you can always change a design - especially with Rails - after committing it. That's what the "Agile" buzzword means on the books.
For internal use, I am creating a site for listing manuals.
Two questions: Have you identified your user community, and asked them exactly what feature here is most important?
to have API documentation with the ability to let people add comments to
the API. In addition, I'd like to have code samples and other sub-sites
which would all allow users to add comments.
That sounds like a Blog with links out to books. You know - like 95% of all the Rails insiders' vanity sites out there. Why not download such a blog, install it, and then ask your user community what the /next/ most important feature is now?
Now, the first set of relationships is easy:
* manual has many api_pages
Are you sucking the manual itself into the website? If so, why not just stuff PDFs into your /public folder?
* api_page has_many comments
I'm not sure about what to do with comments. As such, all comments
(API, technical articles, howto documents, etc.) are quite similar and
have the same set of attributes - user who posted it, date of posting,
actual body, etc. Based on this idea, I should just have one table for
That's where you need the exact Blog architecture, if not a Blog for your base code.
I'm confused about how I would set up the relationships? If I had a
table called api_comments, then I could have a foreign key api_page_id
that would do the necessary. But, if I use the same table for all types
of comments, what do I do? Should I have a foreign key for all the
types of pages? Should I be using STI?
Your post doesn't make something clear. Are the comments going to call-out from specific paragraphs inside the documents? If so, wouldn't the URI specification itself work? I don't know about PDFs (which were my idea), but you could just point into a document using http://my.private.server/docs/my_document.html#my_paragraph , right?
Am I thinking too much? What would your idea for this be?
One of the Rails samples out there for polymorphic data tables (/Rails Recipes/?) starts with a "tumblelog". You could try one of those to get started.