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.
ASCII is an acronym for American Standard Code for Information Interchange. The ASCII set consists of 7-bit codes that represent 128 standard characters, including letters, numbers, and symbols. The first 128 characters in the ASCII set, the extended ASCII set, and the ANSI set are the same.
Conceptual thinking deals with conceptualization theory and helps in assessing or dealing with complex situations. This is very important especially while working with user documentation projects or while performing writing of content.
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.
by Jeffrey K. Tyzzer. In 1970, Dr. E.F. Codd's seminal paper "A Relational Model for Large Shared Databanks" was published in Communications of the ACM. This paper introduced the topic of data normalization, so-named because, at the time, President Nixon was normalizing relations with China.
Data normalization is a technique used during logical data modeling to ensure that there is only one way to know a fact, by removing all structures that provide more than one way to know the same fact as represented in a database relation (table). The goal of normalization is to control and eliminate redundancy, and mitigate the effects of modification anomalies -- which are generally insertion and deletion anomalies. (Insertion anomalies occur when the storage of information about one attribute requires additional information about a second attribute. Deletion anomalies occur when the deletion of one fact results in the loss of a second fact).
Normalization There are six generally recognized normal forms of a relation: first normal form, second normal form, third normal form, Boyce/Codd normal form, fourth normal form, and fifth normal form, also called projection/join normal form. Other normal forms (e.g., Domain/Key) exist but will not be discussed here. The normal forms are hierarchical, i.e., each normal form builds upon its predecessor. Although many people consider a relation to be normalized only when it is in third normal form, technically speaking, a relation in only first normal form can be considered...
Sample code often provides the quickest, clearest way to learn how an SDK works. If you have software engineering experience, then you should already know many principles for writing good code. However, what you may not realize is that some of the good practices that you learned for writing good production code do not apply to writing good sample code. Some techniques, such as comments and clear variable names, apply to both production code and sample code. However, there are good reasons to use hard-coded values in sample code, which should be avoided in production code, and there are good reasons to avoid object-oriented designs when writing sample code.
21. Have Client Sign Requirements
When youre finishing an application for a client, nothing is more frustrating than the client telling you that the application is all wrong. Do yourself a favor: During or shortly after the planning stage, be sure to echo to the client what you heard him or her say. Also consider putting your general plan in writing and have both you and your client sign it. This approach makes you a more professional consultant.
23. Master Table
A master table in a multitable relationship is the primary table. For every record in the master table, there can be many records in the detail table. If you are only dealing with one table, then it is the master table. A detail table in a multitable relationship is the table whose records are subordinate to those of the master table. A detail table is also called a slave table, a child table, or a many table.
24. Naming Fields: Choose a Context Name
When naming fields/columns in a table, use ONE name for the data in the field. For example, although states are called provinces and other names in other coutries, use one or the other in the database but not both. Use CompanyState, avoid CompanyStateProvince. Use labels in your website or program to switch context.
25. ODBMS or RDBS?
For several years now, Object Relational databases have intrigued many developers, myself included. Most of us also rely on more traditional RDBMS systems. Well, a debate is raging, and you're invited to join.
32. PSDP Items
A task, requirement item, design item, test script, or defect. Generically you could refer to items in PSDP as software artifacts (especially requirement items, design items, and test scripts). A PSDP Artifact is a feature that links to together a task, requirement item, design item, and test script.
This change management procedure is specific to Prestwood Software Development Process (PSDP). PSDP is our free process we maintain and distribute as well as use with our own clients. Althought this is specific to PSDP, you can read it with an eye toward your own change management procedure. Do you use version control software? Do you use promotion groups?
See What's New in RAD Studio 2010 at a Free Seminar COMING TO A CITY NEAR YOU!
Technology is moving fast. Learn the secrets to getting the most out of RAD Studio 2010 and new Windows technologies by attending the RAD Studio 2010 Tour in a city near you. These free two-hour technical seminars, led by noted experts David Intersimone, Anders Ohlsson, Nick Hodges, or Mike Rozlog, will give you a firsthand look at new capabilities that will make you more productive and successful with Delphi--, C++Builder--, Delphi Prism-- and Embarcadero-- RAD Studio 2010.
Touch the future with Delphi, C++Builder, and Delphi Prism!
40. Software Artifact
Any nugget discovered and developed and used during software development and maintenance. Examples are requirement items, design items, diagrams, test script, and even code itself.
In PSDP, a PSDP Artifact is a specific implementation of the generic software artifact.
A PSDP Artifact is used to work with a software feature from inception through testing. It links together a task, requirement item, design item, and test script. You can edit a PSDP artifact as a whole or expand any of the four linked items to include more details.
44. Standard Delimited Format (SDF)
SDF is an acronym for standard delimited format. An SDF is a text file formatted in a particular style. Each field is enclosed in quotation marks and separated by a comma. Each line ends with a carriage return and a linefeed.
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.
46. Tab-delimited format (TDF)
In a Tab-delimited format (TDF) file, each field is delimited by a tab character. Each record is delimited with a carriage return and line feed. TDF has the advantages of being immune to commas and quotation marks within the data itself.
A large set of technical writing work have grown up and it has started spanning across several domains. Documentation is strictly a requirement by most of the companies when we look at information management techniques as a whole. Over a period of time, the documentation changes need to be tracked and verified including the release changes and changes in development/API. Technical writing is not just limited to software or hardware or products as such. It is existing across several domains. Let us try to understand the various domains in which technical writing offers it role.
Using real world scenarios when you write conceptual documentation for Software Development Kits (SDKs) is a way to give your readers ideas as to how the SDK can be used and to guide them as to what APIs are needed for commonly expected scenarios. This article guides you through how to gather information about scenarios, how to simplify them in order to make good examples, and how to lead developers through which APIs to use.
49. Waterfall Process
With the waterfall approach to developing software, one phase of the development cycle follows the other and the user is involved only at the beginning during the requirements gathering phase and at the end during the acceptance phase. The requirements gathering in the waterfall approach is critical and unless it is 100 percent perfect, the project will fall short. Other processes, including PSDP, involve the end user throughout the process ensuring a better outcome.
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.
The web has "grown up" to the point that many people now feel that it is THE way to deploy virtually everything. However, it is still primarily a document-based interface. Others believe that desktop applications are superior because they can utilize all the power of an operating system. This needn't be a debate because understanding the advantages and disadvantages of each can make it quite simple to identify the ideal deployment technology. There is also "a third way": utilize a web service to serve up data for your desktop application.
Maybe I'm cynical, but as a developer meeting with a prospective client to gather requirements, I always wait for that one "gotcha" that turns a simple, straightforward project into a potential daymare.
54. You Can Help Defeat Disease
An exciting, new grid computing project is underway to discover potential cures for several of the world's most devastating diseases: AIDS, West Nile Virus, and Alzheimer's disease. With virtually no trouble at all, you can be a part of it.
Share your knowledge with the WORLD! In addition to adding comments to existing posts, you can post knowledge you've acquired. We welcome full articles (intro with screen shots), general posts (shorter), and tidbits (tips, FAQs, definitions, etc.).