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.
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.
Critical Thinking skills comes automatically as a writer becomes experienced over a period of time. Learning to write and transforming the ideas into writing help develop critical thinking aspects/skills. A clear set of phases/activities are inititated in the human brain as part of critical thinking. This article helps to understand the learning basics, learning process and the impact of writing that drives critical thinking skills. This is a good read for all our technical writing friends across the globe.
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.
9. Global Dashboard - Metrics for documentation processes
This article presents an overview of the global dashboard and the related metrics for all regions, specifically for documentation teams. This helps the user to understand and gain more knowledge on the metrics, measures and quality standards used for content management, portal management, elearning systems teams.
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.
15. Knowledge Management
An overview of knowledge management in corporate companies with the basics providing information peratining to such knowledge management teams that lead to greater organizational growth and individuals growth also.
The key aspects of learning evolve by sharing or exchanging information with your peers. For a technical writer, it is very much important to focus/target towards a technical topic. This article presents a short information about the key aspects of learning and the methods/techniques used to enable the learning curve.
18. Prestwood Online Style Guide
Use up to four levels within articles (Heading 1..4). Within text, bold language elements and menu options. Use italics to bring attention to non-code things such as companies, important words, etc. Use bold+Italic for embedded topics and follow with a colon. Use the paragraph style for text and preformatted for code. Max width for images is 700 pixels.
Marketing plan is the first prerequisite once the company decides with bringing the product to the market. It is important to analyze market conditions, growth aspects before starting to release any product. A marketing plan document is a good start and plays a very important role in understanding the market better. This plan discusses several different aspects of marketing strategy.
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.
When I took a typing classs (not a keyboarding class, and yes, I know that dates me) I was taught that words had one space between them and sentences had two spaces in between them. Therefore, my thumbs, whose only job was to hit the space bar, learned that when a period was the last key typed, they had to hit the space bar twice instead of only once. They were good at this and were quite proud of their skill.
Now the rules have changed. The convention, especially for�material to be read on a screen, is that sentences have only one space between them. My thumbs have been rebelling. When I type, they want to put TWO spaces after a period. When I am typing something formal, in addition to checking my spelling and grammar, I also need to�check how many spaces are between each sentence.
Luckily, my thumbs are starting to adjust, and I am finding fewer and fewer double spaces between sentences. Thumbs can learn new tricks.
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.
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.
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.
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.
31. who versus whom
"him" is for "whom" and "he" is for "who"
Who is coding that requirement? (He is coding it.)
To whom do we ask about this requirement? (We ask him.)
32. Wink Software -- Author Animated Tutorials
As developers, we can often help our clients (or our marketing efforts) by creating "screen cast" demos or tutorials. Here is a great tool for doing that - and it's free.
33. Writing as a process
Writing applies to any sort of information. However, writing in general is a generic process that involves many components. Writing itself is a big process that includes many things within itself. It is not easy to write and convey information to end user. Writing require experience, grammar skills, domain knowledge, process knowledge, etc. By this, we would be able to understand the importance of writing.
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.).
Tech Writer
Print This
