NetworkManager has been out for quite a while: years, not months. It has
become the standard interface to networking for major distros, e.g., it's what
you now get by default on Fedora and Ubuntu. Yet there appears to be zero
documentation for it.

Here are some issues that are not discussed by the non-existent documentation:

- The system is at least three programs:
      nm-applet
      NetworkManager
      NetworkManagerDispatcher
  The first two of these have man pages that are nothing but placeholders; 
  the third has no man page. So it's rather mysterious who does what. When
  the networking system is behaving oddly, for example, I have no idea what
  effect restarting different parts of it will have.

- Is it possible to manually manage a network interface controlled by
  NetworkManager from the command line? If I connect to a machine that does most
  of its network management with NetworkManager, how would I manage the net
  from the command line?

  How does NetworkManager interact with the standard ifup/ifdown machinery and
  its related scripts? 

- Is it possible to have the system trigger auxiliary programs when networks
  come up or go down? (E.g., I might want to run a script to manage my domain
  name with my current IP address using dynamic DNS.)

- Poking around the system -- which is what the complete lack of
  documentation reduces one to doing -- reveals an
      /etc/NetworkManager
  directory, with interesting substructure. But there's no specification for
  what should go here.
  
Someone put some time and effort into building a really pretty web page at
    http://www.gnome.org/projects/NetworkManager/
with a lovely logo and nice layout. It has no information about the
architecture, config files, control systems, anything. I would be happier 
if there was a dirt-simple, unattractive, logoless web page that actually 
had some useful information on it.

While I'm complaining, let me add that hoping people will play detective on
the system and post their recipes and incantations to wikis where others can
hunt them down with google does not solve the problem.

Managing networks is a pretty essential task. It's amazing to me that such a
critical subsystem is completely undocumented -- not poorly documented, but
*un*documented. Please, please document the system...
    -Olin