Link to home
Start Free TrialLog in
Avatar of Stephen Kairys
Stephen KairysFlag for United States of America

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.
ASKER CERTIFIED SOLUTION
Avatar of Joe Winograd
Joe Winograd
Flag of United States of America image

Link to home
membership
This solution is only available to members.
To access this solution, you must be a member of Experts Exchange.
Start Free Trial
Avatar of Stephen Kairys

ASKER

@Joe - Yeah, that makes sense. And, your saying you've seen this practice elsewhere validates my gut feeling.
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
Same to you, Joe.