Design & Relationships Question

rubyonrails-talk
1

Hi, I have a design question that I'd like to get some inputs on.

For internal use, I am creating a site for listing manuals. It's going 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.

Now, the first set of relationships is easy: * manual has many api_pages * 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 comments?

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?

Am I thinking too much? What would your idea for this be?

Thanks for your inputs! Cheers, Mohit.

2

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?

It's going 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 comments?

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.

3

Hi Philip,

Thanks for the replies - it does give me more to think about.. my answers to your inline questions are inline :slight_smile:

Phlip wrote:

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.

Of course :slight_smile: I'm starting out with exactly that idea actually!

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?

I'm basically dealing with developers - I'm trying to make something like the PHP Manual (http://www.php.net/manual/en/ ) site for one of the technologies that I follow. The idea is to have a central site for all things related to the technology - with manuals & code samples, etc.

It's going 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?

Hmm.. a blog.. I guess it is a bit like a blog or wiki or the manuals site or something similar. I'm playing with the idea of having a developer site where the developers can tag the pages and add community content to the basic manual that is provided by the vendor.

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?   

Actually, my thought process was to have HTML versions of the PDF manual. I didn't plan to just have the PDF there..

* 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 comments?      That's where you need the exact Blog architecture, if not a Blog for your base code.

I think I see what you mean - I should investigate that closer.. I guess this is a CMS of sorts and the Blog architecture might fit it very well..

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?

I'm sure there are many things that my post doesn't make clear :smiley:

I think the PHP manual site illustrates what I mean - there are no PDFs but there is an HTML page which explains a certain concept/ API and developers can add comments to it. Also, there are other sections of the site that have other technical content (like articles or how-to pages) and those have comments too. My question was more about how to model comments across the site - should I just have one table for all comments and figure out a way to see if the specific comment belongs to an API definition or a technical article or something else.. OR should I have a separate table for each type of comment - so, I have api_comments, tech_article_comments, etc.

But, I think your point about the blog makes things generally simpler. Every thing is a post/ page and it can have one/ more comments in it. Perhaps, if I combine it with acts_as_tree, that would give me the parent/ child relationship that manuals -> sections -> pages should have. Then, I should combine it with acts_as_versioned so that we have a history of edits.

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.    I have Rails recipes and I'm going to look at that now!

Thanks, Mohit.