Tech Writing - API Documentation - Hierarchy of Objects


From what I know, if you are documenting a data structure (e.g. JSON) with embedded objects, you might have something like this for the data schema tables:

DISCLAIMER: In the real world, I doubt you'd have a full (e.g.) doctor object embedded in the prescription object. More likely, you'd have a record number for patient, doctor, drug, but the below is useful for this example. :)

Rx Number
Patient Object
Doctor Object
Drug Object

You'd then have tables for the aforementioned objects, which themselves could contain objects:
IdNumbers Object

And in turn...
Now, to the question. I'm documenting an API where some of the embedded objects contain only one field/object. To use the above example, something like:

PRESCRIPTION OBJECT (as before: contains many fields/objects)

DOCTOR OBJECT (Contains one object)
IdNumbers Object

ID NUMBERS OBJECT (Contains one field)

Per the above, would I be overdoing it to have separate data tables for these objects containing only one field/object? If so, I'd need to find a clean way to embed everything in the parent table.

Stephen KairysTechnical Writer - ConsultantAsked:
Who is Participating?
I wear a lot of hats...

"The solutions and answers provided on Experts Exchange have been extremely helpful to me over the last few years. I wear a lot of hats - Developer, Database Administrator, Help Desk, etc., so I know a lot of things but not a lot about one thing. Experts Exchange gives me answers from people who do know a lot about one thing, in a easy to use platform." -Todd S.

ste5anSenior DeveloperCommented:
hmm, it's the problem of an in-memory object graph vs. a serialized version of it.

During serialization you need to choose a strategy depending on you kind of graph. It sounds like you should use reference pointers in serialized version.
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
ste5an - Thank you for your reply. Are you referring to the JSON code itself, or the API document?  I'm working on the latter.

If you are referring to the doc, please clarify "memory object graph"  and "serialized".
Scott McDaniel (Microsoft Access MVP - EE MVE )Infotrakker SoftwareCommented:
If I understand you correctly:

I would think you would only indicate the object contains that embedded object. You would, of course, also need separate documentation that describes the object. For example, in your Doctor object you would have a line indicating it contains a License object. You would also have separate documentation that describes the License object.
Expert Spotlight: Joe Anderson (DatabaseMX)

We’ve posted a new Expert Spotlight!  Joe Anderson (DatabaseMX) has been on Experts Exchange since 2006. Learn more about this database architect, guitar aficionado, and Microsoft MVP.

Stephen KairysTechnical Writer - ConsultantAuthor Commented:
@Scott - Exactly.  And I would do that, if all the objects contain multiple fields.

But, as I traverse down the hierarchy, two of the tree objects contain only one field. My concern is that I'd be overdoing it by creating a table for such a simple structure (object). As a tech writer, I believe in brevity (as long as the message is still conveyed, of course. ;) )

Joe WinogradDeveloperCommented:
> Per the above, would I be overdoing it to have separate data tables for these objects containing only one field/object?

Not at all, imo. I think that it is fine to have separate data tables for objects containing only one field/object. Just one person's opinion, of course. Regards, Joe

Experts Exchange Solution brought to you by

Your issues matter to us.

Facing a tech roadblock? Get the help and guidance you need from experienced professionals who care. Ask your question anytime, anywhere, with no hassle.

Start your 7-day free trial
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Thank you Joe and Scott!
Joe WinogradDeveloperCommented:
You're welcome, Steve. As always, happy to help! Regards, Joe
It's more than this solution.Get answers and train to solve all your tech problems - anytime, anywhere.Try it for free Edge Out The Competitionfor your dream job with proven skills and certifications.Get started today Stand Outas the employee with proven skills.Start learning today for free Move Your Career Forwardwith certification training in the latest technologies.Start your trial today
Technical Writing

From novice to tech pro — start learning today.