src/main/docbkx/preface.xml

<?xml version="1.0" encoding="UTF-8"?>
<preface version="5.0" xml:id="preface" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
<!--
/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
-->
  <title>Preface</title>

  <para>This is the official reference guide for the <link
  xlink:href="http://hbase.apache.org/">HBase</link> version it ships with.
  Herein you will find either the definitive documentation on an HBase topic
  as of its standing when the referenced HBase version shipped, or it
  will point to the location in <link
  xlink:href="http://hbase.apache.org/apidocs/index.html">javadoc</link>,
  <link xlink:href="https://issues.apache.org/jira/browse/HBASE">JIRA</link>
  or <link xlink:href="http://wiki.apache.org/hadoop/Hbase">wiki</link> where
  the pertinent information can be found.</para>

  <para>This reference guide is a work in progress.  The source for this guide can
      be found at <filename>src/main/docbkx</filename> in a checkout of the hbase
      project.  This reference guide is marked up using
      <link xlink:href="http://www.docbook.com/">DocBook</link> from which the
      the finished guide is generated as part of the 'site' build target.  Run
      <programlisting>mvn site</programlisting> to generate this documentation.
      Amendments and improvements to the documentation are welcomed.  Add a
      patch to an issue up in the HBase <link
  xlink:href="https://issues.apache.org/jira/browse/HBASE">JIRA</link>.</para>

  <note xml:id="headsup">
      <title>Heads-up if this is your first foray into the world of distributed computing...</title>
      <para>
          If this is your first foray into the wonderful world of
          Distributed Computing, then you are in for
          some interesting times.  First off, distributed systems are
          hard; making a distributed system hum requires a disparate
          skillset that spans systems (hardware and software) and
          networking.  Your cluster' operation can hiccup because of any
          of a myriad set of reasons from bugs in HBase itself through misconfigurations
          -- misconfiguration of HBase but also operating system misconfigurations --
          through to hardware problems whether it be a bug in your network card
          drivers or an underprovisioned RAM bus (to mention two recent
          examples of hardware issues that manifested as "HBase is slow").
          You will also need to do a recalibration if up to this your
          computing has been bound to a single box.  Here is one good
          starting point:
          <link xlink:href="http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing">Fallacies of Distributed Computing</link>.
          That said, you are welcome.  Its a fun place to be.  Yours, the HBase Community.
      </para>
  </note>
</preface>