Documentation, documentation, documentation ….

Hi Steve,

thanks for your inputs, especially for the Macro documentation.

Alex & Michiel,

thanks for the developer point of view. Unfortunatelly we don't have "technical writer force" as Microsoft has.

But we understand that the documentation is getting more and more important as the product is growing. We would like to prioritize all needs and start to improve our documentation now.

Hi Ralph,

thanks for your inputs!

Regarding your issues with Mobile site, what's was wrong with your sample Mobile site or mobile devices support?

Setting of CSS style sheets in Properties tab -> General tab -> CSS Stylesheet is not new feature in version 5.5...or do you mean another one?

I find your documentation covers in general quite a bit. But it is very often a bit thin.

Example: The mobile site setup. Only 2 pages in the Dev Guide. You include a sample in the corporate web site template (which needs to be setup first), which however is completely undocumented (and actually didn't work either).

This requires reverse engineering. And it took me a while that the mobile style sheet is not set in the Mobile Master Page, but in a new feature in the general property tab...

****

Another point would be to connect your growing knowledge base to your documentation. If there is a KB article that fits a certain topic in the Dev Guide, there should be a reference.

ciao
Ralph

Macro documentation could also do with improving.

There is information scattered around (Appendix in the Developer's Guide, Macros Webinar, occasional forum reference) but no one place where you can go to look up all the available macros.

There are also macros that only exist for specific functionality, such as when sending out a user's login details in an email when a new user registers. These don't seem to be documented at all, and rely on using examples in the Kentico demo sites to know they even exist.

Given macros are so useful, a complete reference of every macro available, including the specific functionality ones, would be very helpful.

Steve

Once you know a function exists, the API documentation is good enough to work out the basics, in most cases.

But the problem is knowing the function is there in the first place.

So what would be really helpful is an introduction to the API. For example:

- We need to know first in general terms how it is organised.
- What are the 10 most commonly used classes?
- Give us some explanation of the purpose of each class, so we know where to look when trying to find a particular function.
- What are the most commonly used helper methods?
- etc

In other words, we need something like a training guide.

An analogy would be someone giving you a C# reference that just lists everything alphabetically, and expecting you to start programming with it. It would be difficult. You need an introduction, some basic examples, some broad concepts, more examples, etc.

It would also be useful to have more examples in the API documentation, like you find in MSDN, but this would probably be less important if the "training guide" described existed.

Hope this is useful feedback.

Steve

IntelliSense documentation is number one for ASPX developers. I often find descriptions such as "Does something" on a DoSomething() method. The name already covers that, the description needs to explain in more detail. I agree on the comment above: "As Microsoft does."

When it comes to documentation, in my experience there are a lot of edge-cases not documented. So most of the docs describe the ideal way, where everything works according to an example. And not how to deal with an exception to the normal situation.

Or explain in more detail _how_ the system works. For example: how would you explain the way that SmartSearch is implemented? Should it be explained that the search results from Lucene are only available to the system internally and that they are discared as soon as the corresponding documents have been fetched from the database. And that is the reason why we can't have the 'real' Lucene excerpts in our SmartSearch results. And that is also the reason that SmartSearch results could only show the _first_ few words from the documents in the results, and not guaranteed to be able to show the excerpt that has received the highest ranking in Lucene and that contains the search term. Trying to figure that out has cost me an afternoon and then some more time.

A much deeper issue is that if the system is complex, you need more documentation. But if the system is straight-forward, you need less documentation. So another way to look at this issue is to see if some parts of the system have not become overly complex. I have become a big fan of convention over configuration, something that is missing in Kentico.

First of all, force your developers make detailed XML-comments for their code. For classes, for methods, properties and so on. As Microsoft does.
Then, it should be great if you provide more info for add-ons developers. By our expirience:
1. We spent much time for undestanding UniGrid control and its XML description. Thus, it will be good if you describe system controls we can use in our work.
2. Masterpages and CMSDesk and CMSSiteManager pages organization upon the whole.

I plan to visit you in June, so we can discuss our problems (as add-ons developers) side-by-side. If you want..