Code reference site for developers

Question

I'm looking for any UI / UX evidence for what makes a good code reference site. The information is a set of entries of classes (which contains properties and methods), subclasses, functions, and hooks (certain calls within functions). The target audience is competent developers and enthusiastic amateur developers.

It's the type of documentation that would usually be pulled out by phpDocumentor, Doxygen, ApiGen and other documentation generation applications.

e.g.

http://demo.phpdoc.org/Clean/

http://demo.phpdoc.org/Responsive/

I'm interested in what UI helps to make a smooth UX for navigating the site as a whole, and how best to highlight the key bits of information a developer would want to know from a single entry.

While there are some examples out there, that generally contain a list of entries on the left (optionally in a separate frame), I'm looking for any studies or explanations about why this might or might not be good for this type of site. Likewise, what aspects of placement, typography and design of the key entry data are important factors in make it a friendly site to use.

Answer 1

I have two answers for this question:

1- 3-30-300 second of finding an information (how to deal with information that can grow)

Showing all the functions with a search bar is a must (clustering them can make it easier).

Secondly these findings should be explained in a summarized way. If user wants to take more information and details about the same function:he can go into deep.

A header and main description should be visible at first. An extended example and related functions come second. And later on, detailed expert functions and explanations should come.

Side bar on the right is the first visible one and it should provide and overall view like the same concept that is used in Operation system help modules and pdf index function.

2- UX starts way before from this point:

UX does not start with the navigation. This answer has more about the style of education and documentation. If you want to know why they are listing and and later on explanation.

When I was learning English in my first years, my teacher suggested me to read dictionary and learn the meanings of the words from a list. One year later, I met with another teacher who was really helped me to learn English. She suggested me to use what i learned in an abstract conversation. When I compared these two approaches, I felt more confident in the second one.

Seeing the results of using something can be done much more faster and using information makes you learn it easier (not always).

If a visitor is reading your documentation;

1. Want to see if it is suitable (potential customers)
2. Want to see how it will be implemented (potential customers)
3. Need more information (returning customer)

API Documentation should not be perceived just all about point 3. It should not be all about functions and what these functions are coming from and where it goes to. It should create some space for playing around with it.

Practicability is a crucial for converting minds and showing the possibilities of the solution. This strategy is working quite good for several sites: www.angularjs.org as I remember one of the first one took this approach and is currently being in use by many developers. Www.codeacademy.org, www.mashape.com also build business around the same idea.

It is good to look at this topic: http://en.wikipedia.org/wiki/Experiential_learning

Hope that it helps.

PS: The target audience is competent developers and enthusiastic amateur developers. Their demand may be different.

Answer 2

There are two different aspects of this question. The first one is the non-code body text of the information explaining code snippets. This piece of information have no specific readability concerns which differs from other, more general user experience rules. Have your grouping and white spacing in order, make good use of color contrast, type faces, line spacing, letter spacing as well as global, local and related navigation. Have content organized, general understandable labels and search capabilities designed for the target audience.

The second part is more tricky and domain specific. The key part here is recognition and the feeling of familiarity. One could play with the idea to mimic the behavior of the most popular IDEs in specific programming languages. For .NET it would be to mimic the presentation and functionality of Visual Studio; for Java maybe NetBeans or Eclipse; for Python code IDLE and so on. I'm not saying to implement full blown IDEs, but navigation functionalities and defaul presentation mode would probably be a good option since following code patterns is very different from reading linear text.

Answer 3

It depends on the language. For classed based languages that tend to relatively deep class hierarchies the hierarchical context of the class provides much useful information. But often there's a module (or package) structure that is orthogonal to the hierarchy structure, and this suggests 2 views (module and hierarchy), and 2 routes to get to a class.

Some languages without classes (e.g. JavaScript) present a challenge as there's not much in the way of (larger scale) structuring constructs built into the language. The structuring constructs are achieved by convention and they vary (node.js has classes by convention, jQuery doesn't really).

So the structure of programming documentation/doc viewer should reflect the structuring principles of the language.