Index: src/documentation/code.dox
===================================================================
--- src/documentation/code.dox	(revision 1e3265cfdde09115536e60489297dfea655c313f)
+++ src/documentation/code.dox	(revision f11c23fb087ac6674948e06cc77219f2907614c1)
@@ -14,5 +14,91 @@
 
 /**
- * \page code How to use the code
+ * \page code How to use and extend the code
+ *
+ * \section code-introduction How to understand the code
+ *
+ * \subsection code-introduction-whats-there What's there already ...
+ *
+ * Generally, you will begin by having to add a certain Action to the code.
+ * Refer to the \ref constructs and (at the very least briefly) go through
+ * all the stuff that is already there. This should give you an idea of what
+ * you do not have to re-invent!
+ *
+ * As soon as you have decided upon all the little things required for your
+ * Action, e.g. you need a LinkedCell construct because of nearest neighbor,
+ * additionally you need access to BondGraph because you need bond distance
+ * information, you want to know how to access and use each of these.
+ *
+ * \subsection code-introduction-whats-not-there What's not there ...
+ *
+ * Not everything is always documented, not everything is always up-to-date.
+ * Search the code or try to look at Actions that are similar to what you
+ * intent. Try to understand how they do and whever your ideas really can't
+ * be realized with the current capabilities of the code.
+ *
+ * If not, it gets more complicated because if one extends the code, one can
+ * proceed in a straight-forward and soon-to-reach-the-goal way or one can
+ * try to realize if one's not generalizing a concept already present and
+ * implement this generalization (and also bring what's already there up to
+ * speed with this new implementation). Of course, before this "refactoring"
+ * (http://en.wikipedia.org/wiki/Code_refactoring) one should have tests in
+ * place that safeguard that the old functionality remains the same, see
+ * \ref tests. From this generalization your concept should then be easier
+ * to implement.
+ *
+ * Last but not least, see \ref future for what some of the areas are where
+ * the code needs extension or refactorization. Maybe somethings close to what
+ * you want and you could do it along the way, at the same time getting to
+ * know the code better?
+ *
+ * \section code-howto-use How to use the code
+ *
+ * There are two things that should make it easy for you to get to know the
+ * constructs, i.e. classes, required for your Action besides the documentation
+ * and serve as tiny examples on how to use them:
+ * - unit tests
+ * - regression tests
+ * 
+ * \subsection code-howto-use-unit-tests Unit tests
+ *
+ * Unit tests give you an idea how to use a specific constructs, e.g. they
+ * tell you where to get it (simply \code new LinkedCell \endcode, or rather
+ * \code World::getInstance().getBondGraph() \endcode, because it's a unique
+ * instance) and how to use them because that's exactly what's being tested
+ * there. Just browse through the various(?) test functions implemented in
+ * each of the unit tests or rather the unit tests to the constructs you need.
+ *
+ * \subsection code-howto-use-regression-tests Regression tests
+ *
+ * Regression tests (\ref tests-regressiontests) give you an idea how your
+ * Action eventually can be called (from the command line), what to put in your
+ * \b .def file and how it ends up being the option you have to give.
+ *
+ * \attention Never forget that you are supposed to add a regression test for
+ * your new Action as well, either right now (http://en.wikipedia.org/wiki/Test-driven_development)
+ * or at the very latest once its finished.
+ *
+ * \subsection code-howto-use-last Last but not least
+ *
+ * Search the code with the desired construct as keyword to find out places
+ * where it is internally used, see how it is done there and do the same
+ * in your own Action.
+ *
+ * \section code-introduction-howto-extend How to extend the code
+ *
+ * Once you're certain your requirements are not met, new classes have to be
+ * added. Do some careful thinking whether you add something altogether new or
+ * whether it's already present in some simpler or slightly other form. In the
+ * latter case, try to generalize what's present and build from there. E.g.
+ * FormatParserParameters have been generalized from a simpler implementation
+ * that was just used for the parameters for MpqcParser (know FormatParser<mpqc>
+ * which has been refactored as well). Don't always go all the way, but extend
+ * and generalize when it makes sense, especially when the code is much easier
+ * to use afterwards or just much more powerful (with immediate consequences).
+ *
+ * Again, refer to \ref future to know what's already on the schedule, i. e.
+ * what's already marked for extension or refactoring.
+ *
+ * \section code-reference Further readings
  *
  * \li \ref faq
@@ -21,5 +107,5 @@
  *
  *
- * \date 2011-10-31
+ * \date 2011-11-03
  *
  */
Index: src/documentation/future.dox
===================================================================
--- src/documentation/future.dox	(revision f11c23fb087ac6674948e06cc77219f2907614c1)
+++ src/documentation/future.dox	(revision f11c23fb087ac6674948e06cc77219f2907614c1)
@@ -0,0 +1,61 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file future.dox
+ *
+ * Created on: Nov 03, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page future What's to come up next code-wise
+ *
+ * \section future-refactoring Refactoring the code
+ *
+ * Here is a list of what pieces of the code should be refactored to make them
+ * easier to use:
+ * - Fragmentation and related classes: Just generate the keysets and have a
+ *  pool of hydrogen atoms that are re-used when creating and writing
+ *  fragments. Add and re-add messes up the Id's of the Atom's.
+ * - Tesselation and related classes: Especially, the removing and adding of
+ *  nodes is not fully (and correctly) implemented, see the regression tests
+ *  on convex(!) envelopes (non-convex are working).
+ * - all internal, non-atom related information of FormatParser's should be
+ *  stored in FormatParserParameters (e.g. AtomData line of tremolo)
+ *
+ * \section future-extension Extending the code
+ *
+ * Here the list of what should be implemented to make the code more powerful
+ * and just makes sense given the current constructs.
+ * - LinkedCell should be owned by the World and internally, such that one
+ *  simply may access nearest neighbors (e.g. via Selection of a sphere) but in
+ * \f$ {\cal O}(N) \f$ and not naively \f${\cal} (N^2)\f$.
+ * - LinkedCell should be updateable. Thus it could listen to World's
+ *  notifications when World::AtomInserted or World::AtomRemoved and update.
+ *  Hence, it would always be up-to-date. Combined with the Cachable pattern in
+ *  CodePatterns realizing lazy evaluation (http://en.wikipedia.org/wiki/Lazy_evaluation),
+ *  i.e. when many updates have gathered, we rather re-create the linked cell
+ *  structure, this can easily be made very convenient, fast, and powerful.
+ * - BondGraph should be updataeable. As above it should listen the Worlds'
+ *  notifications and so on (also Cachable ...)
+ * - Tesselation should be a Shape: Such that it can be used for Fillings.
+ * - Tesselation should be loadable/storable from/to file: One the one hand
+ *  this could mean \ref serialization but rather \b .3ds or another file
+ *  format such that structures can filled with some external program and
+ *  filled with a certain algorithm later-on.
+ * - Tesselation: Extend such that the created surface can be pushed away from
+ *  the atoms to resemble the molecular surface (http://en.wikipedia.org/wiki/Molecular_surface)
+ * - all Actions regarding Filling: Filling should be generalized as to get a
+ *  shape and vector of atoms and to do something with it. Especially, not a
+ *  new Action but a token that just tells how to fill and a factory pattern
+ *  behind it that spits out the algorithm how to do it.
+ *
+ *
+ * \date 2011-11-03
+ *
+ */ 
