[rfc] git submodules howto

hi,

i saw several "is there any step by step howto on how to use git submodules?" question on irc, and as far as i think there is none available at the moment

here is how i use it at the moment:

$ mkdir lib
$ cd lib
$ git init
Initialized empty Git repository in .git/
$ echo "libmakefile" > Makefile
$ dg add Makefile
$ git commit -m "libmakefile"
Created initial commit 57c1dce: libmakefile
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 Makefile
$ cd ..
$ mkdir main
$ cd main
$ git init
Initialized empty Git repository in .git/
$ echo "main makefile" > Makefile
$ git add Makefile
$ git commit -m "main makefile"
Created initial commit 8935291: main makefile
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 Makefile
$ git submodule add ../lib lib
Initialized empty Git repository in /home/vmiklos/scm/git/sub/main/lib/.git/
0 blocks
$ git commit -m "added lib submodule"
Created commit 9dbfedf: added lib submodule
 2 files changed, 4 insertions(+), 0 deletions(-)
 create mode 100644 .gitmodules
 create mode 160000 lib
$ cd ..
$ git clone main cloned
Initialized empty Git repository in /home/vmiklos/scm/git/sub/cloned/.git/
0 blocks
$ cd cloned
$ git submodule init
Submodule 'lib' (/home/vmiklos/scm/git/sub/lib/.git) registered for path 'lib'
$ git submodule update
Initialized empty Git repository in /home/vmiklos/scm/git/sub/cloned/lib/.git/
0 blocks
Submodule path 'lib': checked out '57c1dce0e083e9ee50d06111d6aa1523116c2e15'
$ cat Makefile
main makefile
$ cat lib/Makefile
libmakefile

my questions:

1) is this correct? :) i use it and it seem to do what i except, but
maybe it's not correct

2) does this worth adding to the documentation? maybe to a .txt under
Documentation/howto? or to git-submodule.txt?

thanks,
- VMiklos