Design & Relationships Question

Rails
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 S. 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.

–
Phlip
"Pigleg too?", week 1

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 S. 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 (PHP: PHP Manual - Manual ) 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.

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…

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…

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.