Stephen Kairys
asked on
API Document - Where to place list of conventions
I had this question after viewing Writing numbers of 1000 or more with decimals in technical documentation.
Hi again,
My API document (for a query), contains certain conventions I'm informally following:
- Numbers in a floating point calculation are written with a decimal place. (e.g. 100.0).
- Variable/object names in bold.
Accordingly, I plan to add a list of conventions. The question is, where to put it. This doc structure is as follows.
Query 1.
Table of Input Data
Table of Output Data
Table of Error Message Formats
Query 2.
Table of Input Data
Table of Output Data
Table of Error Message Formats
etc.
etc.
My gut feeling is to list the conventions one time, at the top of the document; however, in a large doc, if you're on page 35, do you really want to return to page 1 to remind yourself of the conventions? Maybe have a reminder at the beginning of each query or even each table?
Thanks.
Hi again,
My API document (for a query), contains certain conventions I'm informally following:
- Numbers in a floating point calculation are written with a decimal place. (e.g. 100.0).
- Variable/object names in bold.
Accordingly, I plan to add a list of conventions. The question is, where to put it. This doc structure is as follows.
Query 1.
Table of Input Data
Table of Output Data
Table of Error Message Formats
Query 2.
Table of Input Data
Table of Output Data
Table of Error Message Formats
etc.
etc.
My gut feeling is to list the conventions one time, at the top of the document; however, in a large doc, if you're on page 35, do you really want to return to page 1 to remind yourself of the conventions? Maybe have a reminder at the beginning of each query or even each table?
Thanks.
ASKER CERTIFIED SOLUTION
membership
This solution is only available to members.
To access this solution, you must be a member of Experts Exchange.
ASKER
Thanks, Joe. What a great morning...two EE questions solved...both of which will help me in my current assignment. Cheers!
Very glad to hear that — always happy to help! Have a great day, and if we don't talk again today, have a terrific weekend! Regards, Joe
ASKER
Same to you, Joe.
ASKER