documentation driven development
DESCRIPTION
PyCon 2011 presentation proposing developers write documentation before code. "Don't document your code, code your documentation"TRANSCRIPT
![Page 1: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/1.jpg)
Documentation Driven Development
Corey Oordt @coordt
Saturday, March 12, 2011
![Page 2: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/2.jpg)
Origins
Saturday, March 12, 2011
![Page 3: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/3.jpg)
I’m writing documentation?!
Saturday, March 12, 2011
![Page 4: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/4.jpg)
What was I thinking?
Saturday, March 12, 2011
![Page 5: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/5.jpg)
Saturday, March 12, 2011
![Page 6: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/6.jpg)
Saturday, March 12, 2011
![Page 7: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/7.jpg)
http://www.onesigmaoff.net/?p=40
Saturday, March 12, 2011
![Page 8: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/8.jpg)
1. Write code2. Write documentation3. Rewrite code
Saturday, March 12, 2011
![Page 9: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/9.jpg)
1. Write code2. Write documentation12
3. Rewrite code
Saturday, March 12, 2011
![Page 10: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/10.jpg)
Why?
RANDOMSPECULATION
AHEAD
Saturday, March 12, 2011
![Page 11: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/11.jpg)
The great virtues of a programmer
LazinessImpatienceHubris
Saturday, March 12, 2011
![Page 12: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/12.jpg)
http://www.flickr.com/photos/feen/2574309998/in/set-72157605976407357/Saturday, March 12, 2011
![Page 13: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/13.jpg)
http://www.flickr.com/photos/feen/2574309998/in/set-72157605976407357/Saturday, March 12, 2011
![Page 14: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/14.jpg)
http://www.flickr.com/photos/feen/2573487059/in/set-72157605976407357/Saturday, March 12, 2011
![Page 15: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/15.jpg)
http://www.flickr.com/photos/feen/2573487059/in/set-72157605976407357/Saturday, March 12, 2011
![Page 16: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/16.jpg)
We get functional, but not useable code
Saturday, March 12, 2011
![Page 17: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/17.jpg)
Functional, not Useable
Saturday, March 12, 2011
![Page 18: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/18.jpg)
Functional, not Useable
Saturday, March 12, 2011
![Page 19: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/19.jpg)
The Parable of the Microsoft Engineer
Saturday, March 12, 2011
![Page 20: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/20.jpg)
The Parable of the Microsoft Engineer
It looks like you’re shooting a target.
Would you like help?
Get help with shooting the target
Just shoot the target without help
Don’t show me this tip again
Saturday, March 12, 2011
![Page 21: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/21.jpg)
The Parable of the Microsoft Engineer
It looks like you’re shooting a target.
Would you like help?
Get help with shooting the target
Just shoot the target without help
Don’t show me this tip again
Saturday, March 12, 2011
![Page 22: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/22.jpg)
The Parable of the Microsoft Engineer
It looks like you’re shooting a target.
Would you like help?
Get help with shooting the target
Just shoot the target without help
Don’t show me this tip again
Saturday, March 12, 2011
![Page 23: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/23.jpg)
The Parable of the Microsoft Engineer
Saturday, March 12, 2011
![Page 24: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/24.jpg)
Writing documentation first changes your
perspective
Saturday, March 12, 2011
![Page 25: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/25.jpg)
http://www.gravestmor.com/strips/Saturday, March 12, 2011
![Page 26: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/26.jpg)
http://www.gravestmor.com/strips/Saturday, March 12, 2011
![Page 27: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/27.jpg)
Don’t document your code,code your documentation
Saturday, March 12, 2011
![Page 28: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/28.jpg)
Sometimes coding feels like falling down stairs and landing
on your feet
Saturday, March 12, 2011
![Page 29: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/29.jpg)
http://www.flickr.com/photos/zen/2339658529/
Saturday, March 12, 2011
![Page 30: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/30.jpg)
How do I start?
Saturday, March 12, 2011
![Page 31: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/31.jpg)
http://www.flickr.com/photos/hlkljgk/1227416397/sizes/l/in/photostream/Saturday, March 12, 2011
![Page 32: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/32.jpg)
http://sphinx.pocoo.org/
Saturday, March 12, 2011
![Page 33: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/33.jpg)
Have a default Sphinx setup
Include your favorite template or theme
Saturday, March 12, 2011
![Page 34: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/34.jpg)
Have a default Sphinx setupCustomize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))import $$$$PROJECT$$$$os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'copyright = u'2010, The Washington Times'
# The short X.Y version.version = $$$$PROJECT$$$$.get_version()# The full version, including alpha/beta/rc tags.release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
![Page 35: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/35.jpg)
Have a default Sphinx setupCustomize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))import $$$$PROJECT$$$$os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'copyright = u'2010, The Washington Times'
# The short X.Y version.version = $$$$PROJECT$$$$.get_version()# The full version, including alpha/beta/rc tags.release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
![Page 36: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/36.jpg)
Have a default Sphinx setupCustomize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))import $$$$PROJECT$$$$os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'copyright = u'2010, The Washington Times'
# The short X.Y version.version = $$$$PROJECT$$$$.get_version()# The full version, including alpha/beta/rc tags.release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
![Page 37: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/37.jpg)
Have a default Sphinx setupCustomize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))import $$$$PROJECT$$$$os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'copyright = u'2010, The Washington Times'
# The short X.Y version.version = $$$$PROJECT$$$$.get_version()# The full version, including alpha/beta/rc tags.release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
![Page 38: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/38.jpg)
Have a default Sphinx setup
Create placeholder and boilerplate files
doc_src
_build
_static
_templates
conf.py
getting_started.rst
index.rst
installation.rst
Saturday, March 12, 2011
![Page 39: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/39.jpg)
Have a default Sphinx setup
Modify Makefile to render HTML elsewhere
SPHINXOPTS =SPHINXBUILD = sphinx-buildPAPER =BUILDDIR = _buildDESTDIR = ..
...
html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs @echo @echo "Build finished. The HTML pages are in $(DESTDIR)/docs."
Saturday, March 12, 2011
![Page 40: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/40.jpg)
Have a default Sphinx setup
Modify Makefile to render HTML elsewhere
SPHINXOPTS =SPHINXBUILD = sphinx-buildPAPER =BUILDDIR = _buildDESTDIR = ..
...
html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs @echo @echo "Build finished. The HTML pages are in $(DESTDIR)/docs."
Saturday, March 12, 2011
![Page 41: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/41.jpg)
Have a default Sphinx setup
Modify Makefile to render HTML elsewhere
SPHINXOPTS =SPHINXBUILD = sphinx-buildPAPER =BUILDDIR = _buildDESTDIR = ..
...
html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs @echo @echo "Build finished. The HTML pages are in $(DESTDIR)/docs."
Saturday, March 12, 2011
![Page 42: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/42.jpg)
Have a default Sphinx setup
Allows you to build docs often
Saturday, March 12, 2011
![Page 43: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/43.jpg)
Have a default Sphinx setup
Allows you to build docs often
Saturday, March 12, 2011
![Page 44: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/44.jpg)
Have a default Sphinx setup
See http://github.com/washingtontimes/
django-app-skeleton/
Saturday, March 12, 2011
![Page 45: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/45.jpg)
Jumping off points
http://www.flickr.com/photos/frecklefinger/1369581228/
Saturday, March 12, 2011
![Page 46: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/46.jpg)
Feature Lists.. _feature_list:
Feature List============
* Tags - Using `django tagging <http://code.google.com/p/django-tagging/>`_* Groups * Public * Private * Corp only * Alliance only* Export * xml * copy & paste * `eve dna <http://wiki.eveonline.com/en/wiki/Ship_DNA>`_* Ratings - Up/Down ratting system * `django critic <https://github.com/washingtontimes/django-critic>`_* Disqus Comments* Favorite fittings* Fork Fittings* Version Fittings* Rss/AtomSaturday, March 12, 2011
![Page 47: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/47.jpg)
Feature Lists.. _feature_list:
Feature List============
* Tags - Using `django tagging <http://code.google.com/p/django-tagging/>`_* Groups * Public * Private * Corp only * Alliance only* Export * xml * copy & paste * `eve dna <http://wiki.eveonline.com/en/wiki/Ship_DNA>`_* Ratings - Up/Down ratting system * `django critic <https://github.com/washingtontimes/django-critic>`_* Disqus Comments* Favorite fittings* Fork Fittings* Version Fittings* Rss/Atom
How do you add the tags?How do you browse the tags?
Saturday, March 12, 2011
![Page 48: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/48.jpg)
Feature Lists.. _feature_list:
Feature List============
* Tags - Using `django tagging <http://code.google.com/p/django-tagging/>`_* Groups * Public * Private * Corp only * Alliance only* Export * xml * copy & paste * `eve dna <http://wiki.eveonline.com/en/wiki/Ship_DNA>`_* Ratings - Up/Down ratting system * `django critic <https://github.com/washingtontimes/django-critic>`_* Disqus Comments* Favorite fittings* Fork Fittings* Version Fittings* Rss/Atom
How do you fork the fittings?How do see who has forked your fittings?What happens if they fork your mom?
Saturday, March 12, 2011
![Page 49: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/49.jpg)
Flushing out the initial feature list led
to this much documentation
Saturday, March 12, 2011
![Page 50: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/50.jpg)
Flushing out the initial feature list led
to this much documentation
Saturday, March 12, 2011
![Page 51: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/51.jpg)
Examples of how features will work are flushed out
Saturday, March 12, 2011
![Page 52: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/52.jpg)
Initial hurdles are identified
Saturday, March 12, 2011
![Page 53: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/53.jpg)
Some ideas are reconsidered
Saturday, March 12, 2011
![Page 54: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/54.jpg)
Next Step: Work through issues
Saturday, March 12, 2011
![Page 55: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/55.jpg)
Next Step: Write some step-by-step instructions
Saturday, March 12, 2011
![Page 56: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/56.jpg)
Rough notesStarting Out 1. Create a documentation storage record (it configures and sets up a repository) Name, Repository Type (git, hg), remote, url prefix, etc. 2. Optional: Import a zipped sphinx documentation directory 3. Configure Sphinx Settings Initially it will have to be the editing of a python file until better ways can be devised.That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the DocumentationSphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for every level of the URL structure. So * Directories/Folders/Table of Contents are referenced at URLs ending with a / * Pages are referenced by URLs ending without a /In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page: 1. A directory is created and the page is saved in it. 2. An index.rst file is created in the directory and the page is added to its toctree listing. 3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage 1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved. 2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item. 3. subsection1/index is added to the toctree of the section1/index.rst file.
You can edit the index.rst file by going to either the directory URL (/docs/getting_started/) or the index URL (/docs/getting_started/index) and editing the page.
If you remove an item from the toctree Sphwiki will add it back in the next time you edit that page.You can re-order the items without any problems. Sphwiki only looks for the page's existence within the toctree.
Creating a New Page 1. Make sure you are logged in, if necessary. 2. Go to the URL of the new page 3. You will be prompted that the page doesn't exist, do you want to create it? 4. Say Yes. 5. Start writing.
Saturday, March 12, 2011
![Page 57: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/57.jpg)
Rough notesStarting Out 1. Create a documentation storage record (it configures and sets up a repository) Name, Repository Type (git, hg), remote, url prefix, etc. 2. Optional: Import a zipped sphinx documentation directory 3. Configure Sphinx Settings Initially it will have to be the editing of a python file until better ways can be devised.That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the DocumentationSphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for every level of the URL structure. So * Directories/Folders/Table of Contents are referenced at URLs ending with a / * Pages are referenced by URLs ending without a /In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page: 1. A directory is created and the page is saved in it. 2. An index.rst file is created in the directory and the page is added to its toctree listing. 3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage 1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved. 2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item. 3. subsection1/index is added to the toctree of the section1/index.rst file.
Saturday, March 12, 2011
![Page 58: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/58.jpg)
Rough notesStarting Out 1. Create a documentation storage record (it configures and sets up a repository) Name, Repository Type (git, hg), remote, url prefix, etc. 2. Optional: Import a zipped sphinx documentation directory 3. Configure Sphinx Settings Initially it will have to be the editing of a python file until better ways can be devised.That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the DocumentationSphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for every level of the URL structure. So * Directories/Folders/Table of Contents are referenced at URLs ending with a / * Pages are referenced by URLs ending without a /In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page: 1. A directory is created and the page is saved in it. 2. An index.rst file is created in the directory and the page is added to its toctree listing. 3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage 1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved. 2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item. 3. subsection1/index is added to the toctree of the section1/index.rst file.
Saturday, March 12, 2011
![Page 59: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/59.jpg)
Rough notes
Initially it will have to be the editing of a python file until better ways can be devised.That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the DocumentationSphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for every level of the URL structure. So * Directories/Folders/Table of Contents are referenced at URLs ending with a / * Pages are referenced by URLs ending without a /In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page: 1. A directory is created and the page is saved in it. 2. An index.rst file is created in the directory and the page is added to its toctree listing. 3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage 1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved. 2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item. 3. subsection1/index is added to the toctree of the section1/index.rst file.
You can edit the index.rst file by going to either the directory URL (/docs/getting_started/) or the index URL (/docs/getting_started/index) and editing the page.
If you remove an item from the toctree Sphwiki will add it back in the next time you edit that page.You can re-order the items without any problems. Sphwiki only looks for the page's existence within the toctree.
Creating a New Page 1. Make sure you are logged in, if necessary. 2. Go to the URL of the new page 3. You will be prompted that the page doesn't exist, do you want to create it? 4. Say Yes. 5. Start writing.
Saturday, March 12, 2011
![Page 60: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/60.jpg)
Write a tutorial
Saturday, March 12, 2011
![Page 61: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/61.jpg)
How do I…?
Saturday, March 12, 2011
![Page 62: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/62.jpg)
Research
Saturday, March 12, 2011
![Page 63: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/63.jpg)
In summary
• Code your documentation
• Make a customized documentation skeleton
• Iterate over your documentation
• Find a groove that works for you
Saturday, March 12, 2011
![Page 64: Documentation Driven Development](https://reader034.vdocuments.us/reader034/viewer/2022042623/54c209384a7959750b8b45ed/html5/thumbnails/64.jpg)
Thank You
• Corey Oordt
• http://github.com/coordt
• http://github.com/washingtontimes
• @coordt
Saturday, March 12, 2011