We are looking for feedback and recommendations for the following spec sheet.

PDF
http://www.precharge.com/docs/v1.0/api_integration/guide.pdf

HTML
http://www.precharge.com/docs/v1.0/api_integration/guide.html

The spec sheet is the first public version to our interface with
http://www.precharge.com

The spec sheet outlines the secure, public API interface with
merchants and the preCharge system.

Our goal is the make the spec sheet more user friendly and understandable.

Please review the document and let me know what you think.

Any and all comments are welcome.

Hi supremacy-ga,

The document is generally understandable.  However, it has a few major
problems with the content and some minor problems with the writing.

The biggest problem is that the encoding of the content of a request
is not specified clearly.  The Integration section lists a number of
fields with SQL-style types, but that does not define an encoding into
characters suitable for sending with HTTP.  One could induce the
encoding by studying the example request and the Perl Net::SSLeay
module, but this approach is unnecessarily difficult.

The formatting of responses is clearer, but more detailed information
would be helpful.  Examples that show exactly what text is sent and
received would be very useful, too.

The document takes it for granted that the interface uses SSL/HTTP or
HTTPS.  It would be better to state this important fact explicitly,
rather imply it indirectly by specifying the use of port 443 and the
prefix "https."

Some parts were not clear.  The section on "Using preCharge Security
Keys" needs a rewrite.  It's not clear why the system accepts the
Additional Fields in the second table, nor why anyone would want to
send them.  The "direct link option" mentioned in the Response Types
section is not explained, and it is not clear to what the "preCharge
Merchant Interface" refers.  In the Responses section, it's not clear
what a "BIN number" is.

Those are the main problems with the content.  The writing is
generally understandable, but not very polished, and you may want to
consider engaging a professional writer or editor to improve it.  I
will list some things I noticed, but this is not a complete editorial
review.  All of these picky little things are less important than the
content problems described above.

I don't think it's technically completely correct to refer to this
interface as an "API," as that term denotes an interface between
software components within a program, not a network interface between
two systems.  But I don't think this usage will confuse anyone.

Some of the headings appear to have spaces before question marks. 
These spaces should be removed.

The heading "What is an preCharge?" should not have the "an."

In the first line of that section, "industries" should be "industry's".

I suggest referring to the merchant's customers as "customers" rather
than "clients."  I suggest referring to the preCharge interface as
"invisible" to them rather than "transparent."  "Transparent" suggests
that the interface is located between the merchant and the customer,
but the customer just doesn't see it, while in fact, the interface is
behind the merchant, not between the merchant and the customer.

I suggest numbering the pages of the document.

If the "Security Keys" described in the Introduction are the same as
the "Security Codes" in the Integration section, it would be better to
use a consistent name for them.

The text under the Additional Fields heading is incorrect.

In the Examples, it would be better to identify fields with the names
previously presented in the table.

The last sentence of the paragraph under Response Codes seems unfinished.

The difference between error codes 101 and 106 is not clear.

The sections on Legal Notices and Good Merchant Practices are off the
topic of the network interface between the merchant and preCharge and
perhaps should go into a separate document.  In many cases, the person
implementing the interface will not also be the merchant making policy
decisions, so you may want to address those audiences separately.

I hope this review is helpful.  Please ask for a clarification if
anything is not clear, and good luck with your venture.

--efn

---

Request for Answer Clarification by supremacy-ga on 20 Jul 2004 09:36 PDT

Your review was incredibly helpful.

Just one question.

- How would you recommend addressing the encoding ?

Yes, after the document has been cleaned up, it will be sent over to a
professional editor.

Thank you.

---

Clarification of Answer by efn-ga on 20 Jul 2004 19:35 PDT

Thanks.  I'm glad my comments were useful.

It's hard for me to advise you on how to present the information about
the encoding when I don't know what the information is.  I tried to
look up what the make_form function in the Perl Net::SSLeay module
does, and got nowhere.

My guess is that the encoding is intended to use a standard format
such as the Internet Media Type multipart/form-data, specified in RFC
2388.

http://www.ietf.org/rfc/rfc2388.txt

If this is the case, your document should refer to the relevant
standard, and of course, if your application imposes additional
requirements, they should be documented too.

(The relevant standard may be obvious to persons more familiar with
web applications than I, but you may have readers as ignorant as I, so
it is probably a good idea to specify it explicitly.)

That's about all the advice I can offer with the information I have.

Regards,

--efn

Awesome.