RE: Writing APi documents - best practice
Join the LinkedIn group "API Documentation". Jack DeLand, CSM | 734 972 3026 (cell) | jack.deland (skype) | http://www.linkedin.com/in/jackdeland ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Writing APi documents - best practice
Robert Lauriston wrote: > What language is the API written in? Can't comment on the original question posed, but, FWIW, our API's are written in C++ for some, web services (XML/SOAP) for others, and, more recently, REST for some new web interfaces. For our API documents, in the past 13 to 14 years, I wrote the content in FrameMaker (version 6.0 onwards). Recently, I have switched to LaTeX for new documents and specifications, but have not updated any of the older API documents into LaTeX yet. In terms of general advice for API documentation, I'd say that there is one simple best practice to follow well: Accuracy of information and content is critical. So, for example, using automated document generation from an IDE to "feed" into the writing tool, is extremely useful. Of course, the output from such tools is not the most easily "read", so editing is essential. :) In API's in XML/SOAP, for the documentation for our customers, I use the *actual* WSDL files to create input into FrameMaker (edited appropriately, of course - there is no need to show the content of the WSDL in a trivial way). This ensures accuracy - if the documentation ends up being wrong, well, then the API and code are also wrong in the same way at least! :) For C++ based APIs, I use the include files (the .h files) as input for my content. Again, this ensures consistency and accuracy. In FrameMaker, I also use the .h files to create the FrameMaker variable files (since I use and love BookVars!) to get accuracy. Style, content, and degree/amount of explanation for the API documentation is based on a mix of API documents that I have seen from Microsoft, Sun (pre-Oracle) and Google. I don't know if I would call this best practice per se, of course. :) Finally, a good review process, and feedback from your engineers and the customers (the ultimate users of that documentation) is also a Good Thing. Z ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Writing APi documents - best practice
Hi Hassan, Not quite the direct response to your question, but I found this thread pretty interesting on a Linkedin group - API Docs. You might want to check out similar discussion groups on Google Groups, FB, etc.. Thread: How involved are you with the Javadocs? - http://www.linkedin.com/groups/How-involved-are-you-Javadocs-3709151.S.5794126620629426179?qid=ab169460-d213-4072-b263-044916e4f719&trk=groups_most_recent-0-b-ttl&goback=.gmr_3709151 Regards, David | Senior Content and Community Lead | Illustrator | Elements | Lightroom | Camera Raw 33819 | +91 300 177 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Hassan Chamas Sent: Monday, November 25, 2013 7:17 PM To: framers@lists.frameusers.com Subject: Writing APi documents - best practice Hello Framers, I am trying to find the best practice to write API documents, any advice ? or websites I can find example samples would be greatly appreciated. Regards. Sam C ___ You are currently subscribed to framers as dav...@adobe.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/davidi%40adobe.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Writing APi documents - best practice
What language is the API written in?\ ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Writing APi documents - best practice
Google "Ed Marshal"l. He's done numerous papers and presentations on documenting APIs, and he's very good. Sent from my iPhone On Nov 25, 2013, at 8:46 AM, Hassan Chamas wrote: > Hello Framers, > > I am trying to find the best practice to write API documents, any advice ? or > websites I can find example samples would be greatly appreciated. > > Regards. > > Sam C > ___ > > > You are currently subscribed to framers as mkrupp...@yahoo.com. > > Send list messages to framers@lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscr...@lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/mkrupp128%40yahoo.com > > Send administrative questions to listad...@frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
