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?

[Product update] Infrastructure Analysis Tool is now available with Business Accounts.Learn More

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.
Big Business Goals? Which KPIs Will Help You

The most successful MSPs rely on metrics – known as key performance indicators (KPIs) – for making informed decisions that help their businesses thrive, rather than just survive. This eBook provides an overview of the most important KPIs used by top MSPs.

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 Winograd, Fellow&MVEDeveloperCommented:
> 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 Winograd, Fellow&MVEDeveloperCommented:
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.