1642_Improving_Developer

Improving NeXT's Developer Documentation

written by Developer Publications

NeXT's Developer Publications group conducted an informal survey at the East Coast Developer's Conference in January to determine how the developer documentation could be made more effective. The results highlighted some areas in which the documentation could be made more useful; they also underscored the fact that a wide variety of developers use the system, and have differing needs and interests.
NeXT is continuing to solicit input from developers on how to make the documentation more usable. Please see the survey in Developer_Doc_Survey.rtf.

OPPORTUNITY FOR FEEDBACK
NeXT's Developer Publications group is always trying to improve the developer documentation to help you get the most from NEXTSTEP, the Objective C language, and the development tools. We saw the East Coast NEXTSTEP Developer's Conference held this past January as a great opportunity: a chance to ask hundreds of current and prospective NEXTSTEP developers how they use our documentation, what they've had trouble with in the past, and what they would
like us to improve. Our goal was to verify whether our current plans are on the right track and to learn more about our audience.

We asked conference attendees to fill out a simple questionnaire on where they get information, what they'd like us to improve, and what their background is; we collected 296 responses. The results confirmed some of our assumptions about our audience and the way they work, and
showed that our current plans for the developer documentation are on track. Of course, this survey is quite informal and gives us information about only a part of our entire audience; we took
these results with a few large grains of salt. Nonetheless, we think the results present some good information about the evolving NEXTSTEP developer community. We're continuing to gather more feedback, as well.

WHO ARE NEXTSTEP DEVELOPERS, ANYWAY?
To make sure we understand the kind of people who use our products and therefore our documentation, we asked developers about their backgrounds. The survey respondents came from a
variety of environments and had varying amounts of experience with NEXTSTEP. Although a significant number of the respondents use NEXTSTEP to create financial applications, the
group as a whole included representatives from many industries; each person seemed to have a unique application in mind.

New crop of developers
The respondents' experience programming in NEXTSTEP ranged from a few weeks to a few years. Some had been developing in the environment since the first NeXT computers became available. A significant group, over 30 percent of those surveyed, were evaluating NEXTSTEP at the conference. Figure 10 summarizes the results.

Figure 10: Years of NEXTSTEP development experience

We also asked developers whether they generally work alone or as part of a larger development team. Of those who responded, 23 percent said they develop applications alone compared to 61 percent who work in teams. The rest, about 16 percent, said they work both alone and in teams depending on the type of project.

Wide variety of applications and environments
The developers represented all of NeXT's major markets--financial, telecommunications, healthcare, and government--as well as some others, like education and desktop publishing. There were more developers of financial applications than all others combined. Most of the respondents said they are working on mission-critical custom applications.

The developers listed a wide variety of other development environments they have used. Respondents had developed applications on everything from personal computers to workstations to minicomputers. Their development languages included many varieties of C and C++, as well as Smalltalk, COBOL, and many others. A few people, less than 10 percent, have never used anything other than NEXTSTEP.

SOURCES OF INFORMATION
The documentation is only one of many resources NEXTSTEP developers have to help them. We wanted to see whether developers look up information in the documentation, use the many other resources NeXT provides like Developer Support and NeXTanswers, or simply ask a person down the hall. We listed all the resources we could think of, left blanks for writing others in, and asked respondents to indicate all the ways they find out about NEXTSTEP. Figure 11 shows how many respondents use each resource.

Figure 11: How developers find things out

We were gratified to discover that developers use our documentation as much as any other resource. On-line documentation beat printed documentation, but not by much. We had expected more people to use Header Viewer because it provides quick access to the online documentation from the header files; its lack of use could be due to the newness of this tool.

Many developers prefer to ask each other questions rather than look things up. We were interested to see that over 60 percent of the people we surveyed had access to and made use of the Internet. Colleagues and consultants provide lots of information as well.

The most frequently mentioned other resources were books on NEXTSTEP written by third parties. Several developers listed NEXTSTEP Programming by Simson L. Garfinkel and Michael Mahoney (New York, NY: Springer-Verlag, 1992) as an important source of information.

ROOM FOR IMPROVEMENT
While many respondents said they thought the NEXTSTEP documentation is very good and addresses their needs, others had suggestions for how to improve it.

Don't just tell me, show me
The developers we surveyed suggested many ideas for improvements, but one stood out: more and better examples. As one respondent put it, developers need "good quality real-world examples of technical tips and tricks." We've included many examples in each release and within the current documentation, and others are available through NeXTanswers; nonetheless, it's
clear there's a need for more.

Figure 12: Suggestions for improving the documentation

Respondents also favored updating and expanding the NEXTSTEP Concepts book. One developer suggested "a book that describes the concepts, with code examples, like The NEXTSTEP
Advantage, but more theoretical and a bit deeper." In a similar vein, another asked for "higher-level documentation suggesting design strategies or ways to put the pieces together into finished apps."

Other useful suggestions included:

More graphics, such as charts and diagrams
Better coverage of hardware issues
Information on Interface Builder palette creation [Editor's note: See "Creating Advanced Interface
Builder Palettes" in this issue!]
Details on using C++ with Objective C
Better class overviews and explanations of interclass relationships
More information on client/server application development
Better UNIX, manual pages
More information on project management
Quick "pocket guides"-brief descriptions of the most frequently used methods of the most frequently used objects

Note: One frequent request was for Database Kit documentation--we were pleased to have a few advance copies of the Database Kit Concepts book on hand at the conference.

Better online searching tools
Developers asked for many improvements to the documentation tools, but again one prevailed: better searching within Digital Librarian. For example, one developer asked for a "better way of finding an individual method's documentation inside a huge file." Another requested "more sophisticated queries--AND, OR, and so on--and the ability to do another search on just the query results," while a third wants "weighting of hits."

Figure 13: Suggestions for improving the documentation tools

Several people requested other improvements:

Better context-sensitive Help
Cross-referencing in Header Viewer
Display of object/method dependencies
Digital Librarian bookshelf selection sets

Apparently the trouble isn't all in the tools, though: When asked what information he had trouble finding or understanding in the documentation, one developer noted, "It's a lot easier to find things now that I know what I'm doing."

NOW THAT WE KNOW, WHAT WILL WE DO ABOUT IT?
We're currently working to implement some of the changes the survey responses suggest. For example, we're planning to include many more examples in our documentation, to polish the examples we distribute and to make them more effective learning tools.

We're also considering how to make the on-line documentation as usable as possible. Our goal is to deliver information as transparently as possible, with a minimum of context-switching and window negotiation. We also want to better integrate the information delivery systems with each other and with the development environment as a whole. As much as possible, we want developers to have access to all relevant data and documentation directly, without having to switch to another app. In some cases, we plan to try and provide quick bits of information as part of the interface of the development tools, so you don't have to go through Digital Librarian or Header Viewer to find often-needed information like what arguments are passed to a particular method.

Another change we're working on is gradually making the documentation more task-oriented. This means our first and last question when planning our documentation is always, "How are developers actually going to use this API?" We then aim everything we do at helping developers accomplish their goals. In addition to providing tutorials, we plan to have tasks showing developers how to accomplish commonly performed actions. This allows you to stop spending time figuring out how to do standard tasks--like how to create a subproject--and instead to concentrate on the interesting problems your apps are designed to solve. And we're looking for ways to make the Help more tips-oriented, with links into the full on-line documentation.

Of course, at the same time we're also writing new documentation for future releases and products, and keeping the existing documentation up to date. You won't see all of these improvements at once; however, over the next few releases you'll find the documentation becoming even more useful than it is today. We hope it will help you get the most from NEXTSTEP.

HOW YOU CAN HELP
The Developer's Conference survey was only a beginning--we need your comments, too. Please take a few minutes to let us know what you think of the documentation and to make suggestions, using the survey in Developer_Doc_Survey.rtf. (If you think the documentation is great the way it is, make sure you let us know that as well!)

The Developer Publications group writes all of NeXT's developer-related publications and creates examples for NEXTSTEP kits and frameworks. In addition, the group works with the engineers to help ensure high-quality, consistent, and clean APIs and user interfaces. They can be reached by e-mail at DevPubs_feedback@next.com.
__________________________________________________________________________________

Next Article NeXTanswer #1634 appDidInit:

Previous article NeXTanswer #1639 Discovering the DBTableView Object

Table of contents http://www.next.com/HotNews/Journal/NXapp/Spring1994/ContentsSpring1994.html