Tech Writing - API Documentation - Hierarchy of Objects

Hi,

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. :)

PRESCRIPTION OBJECT
Date
Time
Rx Number
Patient Object
Doctor Object
Drug Object
Directions
etc.


You'd then have tables for the aforementioned objects, which themselves could contain objects:
DOCTOR OBJECT
LastName
FirstName
IdNumbers Object
Address
etc.

And in turn...
ID NUMBERS OBJECT
Licence
DEA
NPI
-----------
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)
License

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.

Thanks!
Steve
LVL 4
Stephen KairysTechnical Writer - ConsultantAsked:
Who is Participating?
 
Joe Winograd, Fellow&MVEConnect With a Mentor DeveloperCommented:
> 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
1
 
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.
0
 
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".
0
Improve Your Query Performance Tuning

In this FREE six-day email course, you'll learn from Janis Griffin, Database Performance Evangelist. She'll teach 12 steps that you can use to optimize your queries as much as possible and see measurable results in your work. Get started today!

 
Scott McDaniel (Microsoft Access MVP - EE MVE )Connect With a Mentor 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.
0
 
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. ;) )

Thanks.
0
 
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Thank you Joe and Scott!
0
 
Joe Winograd, Fellow&MVEDeveloperCommented:
You're welcome, Steve. As always, happy to help! Regards, Joe
0
Question has a verified solution.

Are you are experiencing a similar issue? Get a personalized answer when you ask a related question.

Have a better answer? Share it in a comment.

All Courses

From novice to tech pro — start learning today.