Tech Writing - API Documentation - How do handle embedded (JSON) blocks
Hi,
The question below was generated by needing to document a JSON structure, but I suppose it could apply to other data formats as well.
Suppose I have a structure:
{
name: "John Doe",
address: "1234 Main Street",
vitals: {
hair_color: "brown",
eyes: "blue",
},
DOB: "01-01-2000",
sex: "Male"
}
Normally, I'd create a table with one row per data element. But, then I have the vitals block, which contains two data elements. Should I create a separate table for vitals, even though it contains only two fields? And reference it in the main table?
Thanks,
Steve
The question below was generated by needing to document a JSON structure, but I suppose it could apply to other data formats as well.
Suppose I have a structure:
{
name: "John Doe",
address: "1234 Main Street",
vitals: {
hair_color: "brown",
eyes: "blue",
},
DOB: "01-01-2000",
sex: "Male"
}
Normally, I'd create a table with one row per data element. But, then I have the vitals block, which contains two data elements. Should I create a separate table for vitals, even though it contains only two fields? And reference it in the main table?
Thanks,
Steve
ASKER
Interesting. I should say though that in my case, the fields do not contain ids. So maybe I need two columns with field names...field and subfield?
I may try to send along example when I'm back at my computer. Thanks.
I may try to send along example when I'm back at my computer. Thanks.
ASKER CERTIFIED SOLUTION
membership
This solution is only available to members.
To access this solution, you must be a member of Experts Exchange.
SOLUTION
membership
This solution is only available to members.
To access this solution, you must be a member of Experts Exchange.
> merge the cells in the first column
I don't understand that comment.
> Does this layout seem reasonable?
Yes! The two First Name and Last Name elements (Subfields) are distinguished by having different parent elements (Fields). Perfect!
I don't understand that comment.
> Does this layout seem reasonable?
Yes! The two First Name and Last Name elements (Subfields) are distinguished by having different parent elements (Fields). Perfect!
ASKER
>>Steve: merge the cells in the first column
>Joe: I don't understand that comment.
Apologies for the confusion. I meant that the Patient Name row actually takes two rows (cells). One double-height cell in the first column, with two normal-height cells in the other columns. Thanks.
>Joe: I don't understand that comment.
Apologies for the confusion. I meant that the Patient Name row actually takes two rows (cells). One double-height cell in the first column, with two normal-height cells in the other columns. Thanks.
Ah, got it!
ASKER
Hey Joe, I'm going to credit This answer as the BEST SOLUTION. However, do you mind if I credit myself with
an ASSISTED SOLUTION (no points) for this one:?
Thanks.
an ASSISTED SOLUTION (no points) for this one:?
Thanks.
I don't mind at all. Indeed, that was a very helpful post!
ASKER
:) Thanks.
ASKER
Joe, thank you for pointing me in the right direction.
NOTE: I credited myself with an assisted solution b/c it built on Joe's solution by showing it in tabular format, which is what I'm using in the API doc in question.
Have a good evening.
NOTE: I credited myself with an assisted solution b/c it built on Joe's solution by showing it in tabular format, which is what I'm using in the API doc in question.
Have a good evening.
You're welcome. You have a nice evening, too.
First, the caveat that I know zero about JSON! But your example reminds me a lot of the XML tree structure, and with XML, I've seen structures documented in a single table, but with a column that specifies the parent of each element. This technique will allow you to create a single table instead of multiple ones. In this case, something along these lines:
Regards, Joe