What is it with all these frameworks?它是什麼，與所有這些框架呢？ Why can’t JBoss Seam or even good ‘ol Hibernate give me a simple HelloWorld example anymore?為什麼不能JBoss的煤層，甚至良好』醇休眠給我一個簡單的HelloWorld的例子了嗎？

Also have you noticed how complex it is to setup the whole JBoss Seam in the first place?也有你注意到多麼複雜，它是整個安裝JBoss的煤層擺在首位？

I am a simple person and Stripes looks much simpler.我是一個簡單的人星條旗看起來簡單得多。 They also have a HelloWorld or Calculator, an absolutely simple example which you can build upon and play with.他們也有的HelloWorld或計算器，絕對是個簡單的例子，您可以建立和玩耍。 Also note how the examples are built without database requirement to setup.還注意到，如何例子是建立在沒有數據庫的要求設置。 It took me about 5 minutes to setup and run the first example.我花了約5分鐘，以安裝和運行的第一個例子。 If I were to judge a software solely by its documentation, JBoss Seam fails.如果我要判斷一個軟件完全由它的文件， JBoss的煤層失敗。

I dabbled with Hibernate before. i涉足與Hibernate之前。 Now I need to wet my feet again and I remembered an old question.現在我需要濕我的腳再次和我記得一個老問題。 Why in the world did they have to develop a query language like SQL?為什麼在世界上沒有他們要建立一個查詢語言一樣的SQL呢？ Why not SQL?為什麼不的SQL呢？

The problem with Seam or Hibernate type documentation is that they are not organized with readers in mind, they don’t take the readers step by step into the labyrinth of the mess they have created wonderful software they have created.問題與煤層或Hibernate類型的文件是，他們沒有組織與讀者的心目中，他們不採取讀者一步一步進入迷宮的這個爛攤子，他們創造了精彩的軟件，他們創造了。

Reading each paragraph convinces you that the author was in real hurry , like in the last throes of death, while he was writing these chapters.讀每一段說服你，作者是在真正的匆忙，想在最後的陣痛死亡，而他正在撰寫這些章節。 It makes such chapters almost humanly impossible to understand without feeling absolute disgust and revulsion about software development in general.它使這樣的章節幾乎是人力無法理解而不感到絕對的厭惡和反感和憎惡關於軟件開發的一般問題。 They make development a chore, a never-ending horror story.他們把發展一苦差事，永無休止的恐怖故事。 Everything and their great-anchestors are crammed into these chapters.一切都和他們的偉大- anchestors是塞進這些章節。

The only purpose they serve is to convince the readers to cough up and buy their books.唯一目的，他們所服務的是說服讀者咳嗽和購買他們的書籍。

Do you know why RoR flourish?你知不知道為什麼回彈蓬勃發展呢？ Not because they have something great or convoluted.而不是因為他們有一些偉大的或錯綜複雜。 It is because one fine guy has taken the time to create a framework which makes it simpler to develop applications and not make it even more complex than the problem it solves.這是因為一罰款傢伙已採取的時間建立一個框架，使簡單的開發應用，而不是使它更複雜得多的問題，它解決。

Hibernate and Seams team should read RoR and Stripes documentation before they embark on a massive rewrite of their tomes. Hibernate和煤層隊應改為回彈和條紋的文件之前，他們走上了大規模重寫他們的tomes 。

Even PHP Manual is a tome but a very readable tome.甚至PHP手冊是一個聖多美和普林西比而是一個非常可讀的聖多美和普林西比。 Tomes don’t have to be PITA. tomes不一定要皮塔。

One drawback with Stripes documentation is that it is still minimal.有一個缺點，與條紋的文件是，它仍然是微乎其微。 Tag library javadoc doesn’t substitute for documentation.標籤庫javadoc並不代替文件。

All in all I highly recommend Stripes framework.所有在我強烈推薦的條紋框架。 It solves only half of the puzzle which RoR solves fully.它解決了只有一半的拼圖，其中解決了充分的回報率。 However it does it very well, even better than RoR.但它的確能做到非常好，甚至優於回彈。
With the other half completed, RoR will finally stop roaring so much與另一半完成，回報率將最終停止咆哮了這麼多 ： ）

To All Framework Authors: Please for the love of whoever you love take the effort to make something simple and elegant.所有的框架作者：請為愛你愛誰採取的努力，使一些簡單而優雅。 And please spend twice as much time writing documentation which are for human consumption.並請花兩倍多的時間以書面文件是供人食用。 Please read K&R, PHP Manual etc. to get a hang on writing easy to understand and interesting documents.請閱讀k與R ， PHP手冊等，以獲得坑的寫作易於理解和有趣的文件。

BTW: Hibernate with Annotation has a nice thing going, if only they knew how to document clearly.的BTW ：休眠與詮釋有一個很好的事情去，如果只有他們知道如何文件清楚。

If there is one thing I really hate about today’s java software frameworks, it is their documentation.如果有一件事我真的很恨對今天的Java軟件的框架，這是他們的文件。 The bottomline is framework must make our life simpler.底線是必須的框架，使我們的生活更簡單。

To summarize the points that can be addressed while documenting frameworks are.總結點可以解決的同時，記錄框架。

  • Start with a simple example; very simple one開始與一個簡單的例子;很簡單，一
  • Say a simple story and carry it through the spectrum of broad capabilities說一個簡單的故事，並進行透過譜廣泛的能力
  • Now delve in the complex details and exceptions and overrides.現在探究在複雜的細節和例外和壓倒。
  • Stop flaunting your expertise.停止炫耀您的專業知識。

In times such as this I head over to bile blog.在這樣的時代，作為這方面，我頭給膽汁的博客。 He knows the pain which most framework developers (with the exception of Stripes and RoR) don’t.他知道疼痛，其中大部分的框架內發展商（除條紋和回報率）不。

Update: An article without an example is bland.更新：一篇文章，沒有一個例子是平淡。 So let me illustrate with a simple example from Seam.因此，讓我舉出一個簡單的例子，從煤層。

The heading of the chapter is: Chapter 2.標題一章是： 第2章。 Seam concepts 煤層的概念

The two core concepts in Seam are the notion of a context and the notion of a component.這兩個核心概念，在煤層是概念的背景和概念的一個組成部分。 Components are stateful objects, usually EJBs, and an instance of a component is associated with a context, and given a name in that context.組件狀態的物體，通常ejbs ，和一個實例的一個組成部分，是與相關的背景下，並賦予一個名稱，在此背景。 Bijection provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing component trees to be dynamically assembled, and reassembled by Seam. bijection提供了一種機制，別名內部組件的名稱（例如變量）內容的名稱，允許組成的樹木被動態組裝，並重新由煤層。

Read it once, twice and then tell me if you understand what they are talking about.讀一次，兩次，然後告訴我，如果你明白他們所談論的。 To me it reads like incoherent rambling of technical jargon, not a documentation.對我來說，它讀起來就像相干漫談的技術術語，不是一個文件。

First “context” in this context is not defined despite being mentioned.首屆“背景”在這方面是沒有界定，儘管被提及。 Then they simply include it in a sentence.然後他們只是將它包含在一個句子。

“Components are stateful objects, usually EJBs, and an instance of a component is associated with a context, and given a name in that context.” “組件狀態的物體，通常ejbs ，和一個實例的一個組成部分，是與相關的背景下，並賦予一個名稱，在此背景” 。

I don’t know where to begin.我不知道從何處開始。 Is it too much to expect a proper and meaningful yet simple sentence?是它太多的期望一個適當的和有意義的，但簡單的一句呢？

“Bijection provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing component trees to be dynamically assembled, and reassembled by Seam.” “ bijection提供了一種機制，別名內部組件的名稱（例如變量）內容的名稱，允許組成的樹木被動態組裝，並重新由煤層” 。

Why wasn’t “bijection” introduced earlier?為什麼不是“ bijection ”年初推出的？ What is the context?是什麼背景？
This strange sentence probably makes sense only to a Seams developer.這個奇怪的一句話，大概是有道理的，只有一個煤層開發。

Are they being penalized to write simple meaningful sentences?他們受到懲罰，以書寫簡單的有意義的句子呢？ Have they read their own documentation ever?他們閱讀自己的文件呢？ Or have their brain become soft working on frameworks so as not to be able to comprehend the problem?或有他們的大腦成為軟性的工作框架，以便不能夠理解這個問題呢？
This is merely the tip of iceberg.這只不過是尖端的冰山一角。 Such haphazard, poor quality documentation is all throughout.這種雜亂無章，質量低劣的文件是在整個。