IT SOLUTIONS
Your full service technology partner! 
SDK Bridge, Peter Gruenbaum -Collapse +Expand
-Collapse +Expand
peter2
-Collapse +Expand Profile◄╣
Member Info
Member Narration

POSTS:
KB Posts (7)
KB Comments (6)

KBPOSTSBYTYPE:
Tech Articles

Search peter2:

Advanced
      Print This!  
Personal Account . . .
Peter Gruenbaum
Seattle, WA USA



Real Name:  Peter Gruenbaum
Primary Role:  I.T. Manager
Title:  President
Company:  SDK Bridge
Website:  http://sdkbridge.com
Joined: Jan 2009 (8 years ago)
Visits: 102



Knowledge Base Posts

More...
  KB Article    

Peter Gruenbaum
1. API Documentation Survey Results

In a perfect world, API documentation would contain clear, complete instructions on everything that developers need to know to use your platform. In reality, organizations have limited time and budget to create API documentation, and so organizations need to prioritize to create documentation that is most useful to the people who will use it.

SDK Bridge set out to find out what is most important to the people who use APIs by sending out a survey and asking them. We found, not surprisingly, that many thought that documentation could be better. When asked to rate quantitatively, people rated overviews, sample code, and API references the highest, followed closely by tutorials. When asked for open-ended comments, a large percentage mentioned working sample code as helpful, and an equally high percentage mentioned how important it is that documentation be complete and accurate. Two other important factors that were mentioned by several respondants are (1) it is very helpful to explain why you would use something in addition to how you use it and (2) completeness and accuracy are critical.

Posted to KB Topic: Technical Writing
6 years ago, and updated 6 years ago

Article
Nothing New Since Your Last Visit
5782
Hits

Technical Writing

Peter Gruenbaum
2. Crowd-Sourcing API Documentation

Crowd-sourcing (that is, using Web-based technology to gather API documentation content from your users) has the potential to lower documentation costs and make your documentation more relevant. However, relying solely your developer community to provide documentation will result in uneven quality and coverage. I recommend a hybrid approach, where professional programmer/writers write parts of the documentation, as well as rewrite and polish content from the community. Several tools are available that enable communities to contribute documentation content. 

Posted to KB Topic: Technical Writing
7 years ago
(1 Comments )

Article
Nothing New Since Your Last Visit
10300
Hits

Technical Writing

Peter Gruenbaum
3. Web API Documentation

The number of Web APIs is growing rapidly, especially with the increasing popularity of Software as a Service. Because Web APIs are still fairly new, the quality and format of their documentation varies a great deal. Good documentation is important for Web APIs because experimentation is more difficult than with local APIs. Because Web APIs are language-neutral, you may need to write sample code in a variety of different languages. Be sure to cover authentication, error handling, and HTTP information.

Posted to KB Topic: Technical Writing
7 years ago, and updated 7 years ago
(3 Comments , last by Anonymous )

Article
Nothing New Since Your Last Visit
21383
Hits

Technical Writing

Peter Gruenbaum
4. The Five Biggest API Documentation Mistakes and How to Avoid Them

Good API documentation can have a tremendous impact on whether a software platform is adopted. However, too often API documentation ends up being confusing and hard to follow, which results in developers choosing another way to accomplish their goals. This article describes five common mistakes that are made in creating API documentation and describes solutions to avoiding those mistakes. Following good API documentation practices can provide developers with the content that they need to be able to take full advantage of a software platform's capabilities. 

Posted to KB Topic: General, Getting Started, etc.
8 years ago, and updated 7 years ago
(9 Comments , last by peter2 )

Article
Nothing New Since Your Last Visit
16079
Hits

Technical Writing

Peter Gruenbaum
5. Survey on SDK Documentation

A survey was sent to software developers and other software professionals to ask what was important in SDK documentation and where they would like to see improvement. The results indicated that the current state of typical SDK documentation is "Fair", which was the middle choice of five ("Excellent" to "Unusable"). The answers to multiple choice questions indicated that overviews, API references, sample code, and tutorials were all considered high importance, whereas blogs and forums were considered less important. When asked to write what they considered important, sample code was mentioned in 61% of the responses and overviews were mentioned in 30% of the responses. Also mentioned as important were help getting started, explanations of why something should be used, accuracy of information, and the ability to find information easily.

Posted to KB Topic: Technical Writing
8 years ago

Article
Nothing New Since Your Last Visit
19701
Hits

Technical Writing
More...

KB Comments

More...
Read +Add Comment
Somehow I kept missing that little "Edit" button under the article. Once I found it, it was simple to change the status to Submitted.
Posted 7 years ago
Regarding...
Message Board How To Guide
Guide to using our message boards
Read +Add Comment
I wrote an article, saved it as a draft, came back to it a few days later, and now I can't figure out how to publish it. When I was writing it, there was a publish button. But now that I view it as a draft, there's no button any more. How do I do this? Thanks, Peter
Posted 7 years ago
Regarding...
Message Board How To Guide
Guide to using our message boards
Read +Add Comment
I do think you need to make a distinction between API design and API documentation. You're right that the writer should really be involved in the design process, but the reality is that just doesn't happen very often in industry. The writer is typically brought in at the tail end of the process. Diagrams -- yes, they can be useful. They just didn't make it into the top five. Context is important, too. I believe you could see that best through good sample code.
Posted 7 years ago
Regarding...
The Five Biggest API Documentation Mistakes and How to Avoid Them

Good API documentation can have a tremendous impact on whether a software platform is adopted. However, too often API documentation ends up being confusing and hard to follow, which results in developers choosing another way to accomplish their goals. This article describes five common mistakes that are made in creating API documentation and describes solutions to avoiding those mistakes. Following good API documentation practices can provide developers with the content that they need to be able to take full advantage of a software platform's capabilities. 

More...
-
   Contact Us!
 
Have a question? Need our services? Contact us now.
--Mike Prestwood

Call: 916-726-5675

email: info@prestwood.com


Go ahead!   Use Us! Call: 916-726-5675 


©1995-2017 Prestwood IT Solutions.   [Security & Privacy]