Ayende @ Rahien

My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:


+972 52-548-6969

, @ Q c

Posts: 6,128 | Comments: 45,546

filter by tags archive

Kobe – When the documentation is the only delivery that matters

time to read 2 min | 251 words

When comparing the Kobe code base to the Kobe documentation, I am starting to get a sinking feeling. The documentation is really nice, the code is anything but.

When you put out guidance, the documentation is nice, but it is the code that people are going to look it, learn and try to emulate. And when you put out something that doesn’t meet basic parameters for good software, that is a huge problem.

With Oxite, Microsoft had the excuse of it being slipped out without anyone noticing. This time it is official, it has passed the proper review procedure, and is explicitly marketed as “intended to guide you with the planning, architecting, and implementing of Web 2.0 applications and services.”

Sorry, that is entirely unacceptable.

Putting something like that out there as guidance is actively doing harm to the community as a whole. It means that people who would look at that and try to use what they see there are going to get bitten by bad practices, bad architecture and overly complex and redundant approaches.

Phil Haack said that: “I was part of a high-level review and I felt most of the app that I saw was reasonably put together.”

I submit that high level review of such guidance packages is absolutely not sufficient. You have to get people to do a full review cycle of that, which include the code, the documentation, the reasoning and anything else that is going out there.


Kyle Szklenski

What exactly is a "high-level review"? A discussion on the documentation? A look at the general design of the application, maybe in some form of UML or other design language? I can't imagine it's the latter - any repository interface that has something like 60 functions should automatically send up a warning signal. Hell, any interface at all that has 60 functions ought to cause the person who wrote it to be fired.


I'm gonna guess haack's high level review meant looking at the documentation and some developer overview of the app concepts without much discussion of the code.


I wrote a follow-up comment to my post that talks about this a bit and asks the question of how we can make it better.


The review was informal. They showed us some slides of the high-level architecture. They told me about their data access and they were using the Repository pattern.

Then we looked at an action, a view, etc... Some of it was clean, some of it wasn't. I gave them some feedback, and we went our merry ways.

What I didn't do was go through a line-by-line code review, nor did I explore the source. Obviously now, I wish I had. But at the time, I was pressed for time and their questions were really focused on how to do things the MVC way. I warned them about Oxite, which they were aware of, and went on my way.

If you don't mind, please comment on my post if you have suggestions how we should handle this better in the future.

Comment preview

Comments have been closed on this topic.


  1. The low level interview question - 13 hours from now
  2. The worker pattern - 4 days from now

There are posts all the way to May 30, 2016


  1. The design of RavenDB 4.0 (14):
    26 May 2016 - The client side
  2. RavenDB 3.5 whirl wind tour (14):
    25 May 2016 - Got anything to declare, ya smuggler?
  3. Tasks for the new comer (2):
    15 Apr 2016 - Quartz.NET with RavenDB
  4. Code through the looking glass (5):
    18 Mar 2016 - And a linear search to rule them
  5. Find the bug (8):
    29 Feb 2016 - When you can't rely on your own identity
View all series



Main feed Feed Stats
Comments feed   Comments Feed Stats