--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/helpers.texi	Fri Oct 16 07:13:05 2009 -0700
@@ -0,0 +1,42 @@
+@node Helpers
+@chapter Helpers
+
+The above chapters introduced you to various ns-3 programming concepts
+such as smart pointers for reference-counted memory management, attributes,
+namespaces, callbacks, etc.   Users who work at this low-level API
+can interconnect ns-3 objects with fine granulariy.  However, a
+simulation program written entirely using the low-level API would
+be quite long and tedious to code.  For this reason, a separate so-called
+``helper API'' has been overlaid on the core ns-3 API.  If you have read
+the ns-3 tutorial, you will already be familiar with the helper API,
+since it is the API that new users are typically introduced to first.
+In this chapter, we introduce the design philosophy of the helper
+API and contrast it to the low-level API.  If you become a heavy
+user of ns-3, you will likely move back and forth between these
+APIs even in the same program.
+
+The helper API has a few goals:
+@enumerate
+@item the rest of @code{src/} has no dependencies on the helper API;
+anything that can be done with the helper API can be coded also at
+the low-level API
+@item @strong{Containers:}  Often simulations will need to do
+a number of identical actions to groups of objects.  The helper
+API makes heavy use of containers of similar objects to which similar
+or identical operations can be performed.
+@item The helper API is not generic; it does not strive to maximize
+code reuse.  So, programming constructs such as polymorphism and
+templates that achieve code reuse are not as prevalent.  For instance,
+there are separate CsmaNetDevice helpers and PointToPointNetDevice
+helpers but they do not derive from a common NetDevice base class.
+@item The helper API typically works with stack-allocated (vs.
+heap-allocated) objects.  For some programs, ns-3 users may not
+need to worry about any low level Object Create or Ptr handling;
+they can make do with containers of objects and stack-allocated helpers
+that operate on them.
+@end enumerate
+
+The helper API is really all about making ns-3 programs easier to
+write and read, without taking away the power of the low-level 
+interface.  The rest of this chapter provides some examples of
+the programming conventions of the helper API.