Documentation, documentation, documentation ….

   —   
As we noted earlier, version 6.0 will be one of the biggest releases ever and we are taking this goal seriously. One part of this release will be also improved documentation.  
We have “tons” of documents – we have Tutorials, User guide, Guides for E-commerce/Community Site/Personal sites, Developer guide etc. The documentation is available for download or you can access it directly from the browser at http://devnet.kentico.com/Documentation.aspx. But on other hand, we got several times requests for the improvements of the documentation.
We heard several times “Please improve API documentation”, “Please add more examples”, “Please add more details” etc. These requirements are fine that we know you are missing something, but they are too general. So, we are not sure what the best improvements that fully fit all needs are.
Our team joined new technical writers that will help us to improve it. And it will be longer process through new versions that can’t be done in one day/week/month.
Please, send us your recommendation where and how we can improve the documentation. You can suggest and vote at http://kentico.uservoice.com/forums/33828-documentation or just post your comment here.
More details we get more improvements we can do.
 
Share this article on   LinkedIn Google+

Comments

Michal Neuwirth commented on

Hi Steve,

thanks for your inputs, especially for the Macro documentation.

Michal Neuwirth commented on

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.

Michal Neuwirth commented on

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?

Ralph Spandl commented on

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

Appetere Web Solutions commented on

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

Appetere Web Solutions commented on

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

Michiel commented on

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.

Alex Rybin commented on

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..