1

I'm documenting a block of computer code and would like to make it clear and concise. I'm describing a function that populates a field on a user input screen. Here's my best shot but it still seems confusing because the 'in the', 'on the', 'for a' seem like a lot of prepositions for one sentence.

This function returns the WINGNUT_SELLER_CODE that appears in the 'Vendor' field  
on the 'THREADED_NUTS' screen for a given NUT_ID. 

Questions:
[1] How can I rewrite this to make it easier to understand?
[2] What about 'that appears' vs. 'which appears' when should I use 'that' and 'which' ?

4
  • Are WINGNUT_SELLER_CODE and NUT_ID function paramaters/return values? If so, they're quasi-proper nouns and you should treat them as such. What about THREADED_NUTS? Could we see the function signature? Sep 6, 2011 at 17:25
  • Yes, wingnut_seller_code and nut_id are return/input parameters respectively. Threaded_nuts is the name of the form. Here's the function signature function f_get_vend_code(v_nut_id varchar2) return varchar2;
    – zundarz
    Sep 6, 2011 at 18:53
  • Maybe if you showed an diagram in addition to the explanation it would be clearer, for example a shape representing the function, with arrows for the input and output values. Sep 6, 2011 at 19:15
  • This is an older question. It's been bumped by the system because it's been retagged, as per this meta post. Also, requests for the revision or critique of a single sentence are normally closed here, but this has already been asked and answered. Jun 8, 2012 at 16:25

4 Answers 4

4

Maybe break it into two sentences?

When you send this function a NUT_ID, it returns a WINGNUT_SELLER_CODE. This code is from the'THREADED_NUTS' screen in the 'Vendor' field.

I almost always use "that". (Every copy editor I've ever encountered seems determined to eradicate all uses of "which".

2
  • 2
    Hi Lynn. I am a copy editor who deeply mourns the loss of "which" in front of properly dependent clauses. I would switch all those "that"s back to "which"s if I could. :) Sep 6, 2011 at 18:27
  • 2
    Ha! I knew some of my whiches had to be correct, I couldn't be wrong every single time. :) Sep 6, 2011 at 19:13
4

Edited based on comments:

Given the following function declaration:

f_get_vend_code(v_nut_id varchar2) return varchar2;

I would write the description as follows:

This function takes a nut ID (NUT_ID) and returns the vendor's seller code (WINGNUT_SELLER_CODE) for this form. If NUT_ID is not set (blah blah blah). If the function cannot find a valid seller ID it (does something).

Note: I'm using Java idioms because those are the ones I'm familiar with. I'm assuming that "takes (a parameter)" and "returns" are meaningful for your audience too; you should verify that by reading other API documentation for this language. I am also assuming that the values you originally used, e.g. NUT_ID, are meaningful even though they don't appear in the signature; if that's not the case then I would omit them in the description.

Also note that I went beyond your original question to cover invalid parameters and error conditions. Good API documentation goes beyond what they can get from just reading the signature and tells them what they wouldn't be able to figure out otherwise.

0

Try

For a given NUT_ID, this function provides the WINGNUT_SELLER_CODE that fills the 'Vendor' field on the 'THREADED_NUTS' screen.

Your original comment is

This function returns the WINGNUT_SELLER_CODE that appears in the 'Vendor' field
on the 'THREADED_NUTS' screen for a given NUT_ID.

0

Given your comment to Monica, it seems to me that your original description goes way beyond what the function actually does. In particular, the function does not itself display the seller id, but instead returns it to some other code that displays it. The f_get_vend_code() function itself does not interact with either the form or the field, so there's no need to mention them.

If that's true, describe only what the function does: "This function returns the vendor code for the nut identified by NUT_ID."

Also: The name of the function and its parameter seem almost sufficient documentation in and of themselves. Could you improve those names so as to make the documentation unnecessary? At least spell out "vendor" instead of unnecessarily abbreviating it as "vend". If you do that, what's left for the documentation to convey?

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.