0
Documentation Driven                          Development                           Corey Oordt @coordtSaturday, March 12,...
OriginsSaturday, March 12, 2011
I’m writing                           documentation?!Saturday, March 12, 2011
What was I thinking?Saturday, March 12, 2011
Saturday, March 12, 2011
Saturday, March 12, 2011
http://www.onesigmaoff.net/?p=40Saturday, March 12, 2011
1. Write code                           2. Write documentation                           3. Rewrite codeSaturday, March 12...
12. Write documentation                       21. Write code                        3. Rewrite codeSaturday, March 12, 2011
Why?                             RANDOM                           SPECULATION                              AHEADSaturday, ...
The great virtues of a                               programmer                           Laziness                        ...
http://www.flickr.com/photos/feen/2574309998/in/set-72157605976407357/Saturday, March 12, 2011
http://www.flickr.com/photos/feen/2574309998/in/set-72157605976407357/Saturday, March 12, 2011
http://www.flickr.com/photos/feen/2573487059/in/set-72157605976407357/Saturday, March 12, 2011
http://www.flickr.com/photos/feen/2573487059/in/set-72157605976407357/Saturday, March 12, 2011
We get functional, but                            not useable codeSaturday, March 12, 2011
Functional, not UseableSaturday, March 12, 2011
Functional, not UseableSaturday, March 12, 2011
The Parable of the                           Microsoft EngineerSaturday, March 12, 2011
The Parable of the                           Microsoft Engineer                                            It looks like y...
The Parable of the                           Microsoft Engineer                                            It looks like y...
The Parable of the                           Microsoft Engineer                                            It looks like y...
The Parable of the                           Microsoft EngineerSaturday, March 12, 2011
Writing documentation                       first changes your                           perspectiveSaturday, March 12, 2011
http://www.gravestmor.com/strips/Saturday, March 12, 2011
http://www.gravestmor.com/strips/Saturday, March 12, 2011
Don’t document your code,            code your documentationSaturday, March 12, 2011
Sometimes                           coding feels                            like falling                           down st...
http://www.flickr.com/photos/zen/2339658529/Saturday, March 12, 2011
How do I start?Saturday, March 12, 2011
http://www.flickr.com/photos/hlkljgk/1227416397/sizes/l/in/photostream/Saturday, March 12, 2011
http://sphinx.pocoo.org/Saturday, March 12, 2011
Have a default                                 Sphinx setup                           Include your favorite template or th...
Have a default                            Sphinx setup                            Customize the conf.py           import s...
Have a default                            Sphinx setup                            Customize the conf.py           import s...
Have a default                            Sphinx setup                            Customize the conf.py           import s...
Have a default                            Sphinx setup                            Customize the conf.py           import s...
Have a default                                 Sphinx setup                       Create placeholder and boilerplate files...
Have a default                            Sphinx setup                Modify Makefile to render HTML elsewhere           S...
Have a default                            Sphinx setup                Modify Makefile to render HTML elsewhere           S...
Have a default                            Sphinx setup                Modify Makefile to render HTML elsewhere           S...
Have a default                              Sphinx setup                           Allows you to build docs oftenSaturday,...
Have a default                              Sphinx setup                           Allows you to build docs oftenSaturday,...
Have a default                                  Sphinx setup                           See http://github.com/washingtontim...
Jumping off points                                      http://www.flickr.com/photos/frecklefinger/1369581228/Saturday, Ma...
Feature Lists        .. _feature_list:        Feature List        ============                 * Tags - Using `django tagg...
Feature Lists        .. _feature_list:        Feature List        ============                           How do you add th...
Feature Lists        .. _feature_list:        Feature List        ============                 * Tags - Using `django tagg...
Flushing out the                           initial feature list led                                to this much           ...
Flushing out the                           initial feature list led                                to this much           ...
Examples of how features                           will work are flushed outSaturday, March 12, 2011
Initial hurdles are identifiedSaturday, March 12, 2011
Some ideas are reconsideredSaturday, March 12, 2011
Next Step: Work through issuesSaturday, March 12, 2011
Next Step: Write some step-by-                           step instructionsSaturday, March 12, 2011
Rough notes                           Starting Out                            1. Create a documentation storage record (it...
Rough notes    Starting Out     1. Create a documentation storage record (it configures and sets up a repository)        N...
Rough notes    Starting Out     1. Create a documentation storage record (it configures and sets up a repository)        N...
Thats it! Now the table of contents is served at http://sitename.com/prefix/    Structure of the Documentation            ...
Write a tutorialSaturday, March 12, 2011
How do I…?Saturday, March 12, 2011
ResearchSaturday, March 12, 2011
In summary                    • Code your documentation                    • Make a customized documentation skeleton     ...
Thank You                    •      Corey Oordt                    •      coreyoordt@gmail.com                    •      h...
Upcoming SlideShare
Loading in...5
×

Documentation Driven Development

6,037

Published on

PyCon 2011 presentation proposing developers write documentation before code. "Don't document your code, code your documentation"

Published in: Technology
0 Comments
6 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
6,037
On Slideshare
0
From Embeds
0
Number of Embeds
6
Actions
Shares
0
Downloads
46
Comments
0
Likes
6
Embeds 0
No embeds

No notes for slide

Transcript of "Documentation Driven Development"

  1. 1. Documentation Driven Development Corey Oordt @coordtSaturday, March 12, 2011
  2. 2. OriginsSaturday, March 12, 2011
  3. 3. I’m writing documentation?!Saturday, March 12, 2011
  4. 4. What was I thinking?Saturday, March 12, 2011
  5. 5. Saturday, March 12, 2011
  6. 6. Saturday, March 12, 2011
  7. 7. http://www.onesigmaoff.net/?p=40Saturday, March 12, 2011
  8. 8. 1. Write code 2. Write documentation 3. Rewrite codeSaturday, March 12, 2011
  9. 9. 12. Write documentation 21. Write code 3. Rewrite codeSaturday, March 12, 2011
  10. 10. Why? RANDOM SPECULATION AHEADSaturday, March 12, 2011
  11. 11. The great virtues of a programmer Laziness Impatience HubrisSaturday, March 12, 2011
  12. 12. http://www.flickr.com/photos/feen/2574309998/in/set-72157605976407357/Saturday, March 12, 2011
  13. 13. http://www.flickr.com/photos/feen/2574309998/in/set-72157605976407357/Saturday, March 12, 2011
  14. 14. http://www.flickr.com/photos/feen/2573487059/in/set-72157605976407357/Saturday, March 12, 2011
  15. 15. http://www.flickr.com/photos/feen/2573487059/in/set-72157605976407357/Saturday, March 12, 2011
  16. 16. We get functional, but not useable codeSaturday, March 12, 2011
  17. 17. Functional, not UseableSaturday, March 12, 2011
  18. 18. Functional, not UseableSaturday, March 12, 2011
  19. 19. The Parable of the Microsoft EngineerSaturday, March 12, 2011
  20. 20. 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 againSaturday, March 12, 2011
  21. 21. 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 againSaturday, March 12, 2011
  22. 22. 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 againSaturday, March 12, 2011
  23. 23. The Parable of the Microsoft EngineerSaturday, March 12, 2011
  24. 24. Writing documentation first changes your perspectiveSaturday, March 12, 2011
  25. 25. http://www.gravestmor.com/strips/Saturday, March 12, 2011
  26. 26. http://www.gravestmor.com/strips/Saturday, March 12, 2011
  27. 27. Don’t document your code, code your documentationSaturday, March 12, 2011
  28. 28. Sometimes coding feels like falling down stairs and landing on your feetSaturday, March 12, 2011
  29. 29. http://www.flickr.com/photos/zen/2339658529/Saturday, March 12, 2011
  30. 30. How do I start?Saturday, March 12, 2011
  31. 31. http://www.flickr.com/photos/hlkljgk/1227416397/sizes/l/in/photostream/Saturday, March 12, 2011
  32. 32. http://sphinx.pocoo.org/Saturday, March 12, 2011
  33. 33. Have a default Sphinx setup Include your favorite template or themeSaturday, March 12, 2011
  34. 34. Have a default Sphinx setup Customize 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 = udjango-$$$$PROJECT$$$$ copyright = u2010, 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
  35. 35. Have a default Sphinx setup Customize 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 = udjango-$$$$PROJECT$$$$ copyright = u2010, 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
  36. 36. Have a default Sphinx setup Customize 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 = udjango-$$$$PROJECT$$$$ copyright = u2010, 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
  37. 37. Have a default Sphinx setup Customize 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 = udjango-$$$$PROJECT$$$$ copyright = u2010, 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
  38. 38. Have a default Sphinx setup Create placeholder and boilerplate files doc_src _build _static _templates conf.py getting_started.rst index.rst installation.rstSaturday, March 12, 2011
  39. 39. Have a default Sphinx setup Modify Makefile to render HTML elsewhere SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build DESTDIR = .. ... html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs @echo @echo "Build finished. The HTML pages are in $(DESTDIR)/ docs."Saturday, March 12, 2011
  40. 40. Have a default Sphinx setup Modify Makefile to render HTML elsewhere SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build DESTDIR = .. ... html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs @echo @echo "Build finished. The HTML pages are in $(DESTDIR)/ docs."Saturday, March 12, 2011
  41. 41. Have a default Sphinx setup Modify Makefile to render HTML elsewhere SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build DESTDIR = .. ... html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs @echo @echo "Build finished. The HTML pages are in $(DESTDIR)/ docs."Saturday, March 12, 2011
  42. 42. Have a default Sphinx setup Allows you to build docs oftenSaturday, March 12, 2011
  43. 43. Have a default Sphinx setup Allows you to build docs oftenSaturday, March 12, 2011
  44. 44. Have a default Sphinx setup See http://github.com/washingtontimes/ django-app-skeleton/Saturday, March 12, 2011
  45. 45. Jumping off points http://www.flickr.com/photos/frecklefinger/1369581228/Saturday, March 12, 2011
  46. 46. 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
  47. 47. Feature Lists .. _feature_list: Feature List ============ How do you add the tags? * Tags - Using `django tagging <http://code.google.com/p/django- How do you browse the tags? 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
  48. 48. 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>`_ How do you fork the fittings? * Disqus Comments How do see who has forked your fittings? * Favorite fittings What happens if they fork your mom? * Fork Fittings * Version Fittings * Rss/AtomSaturday, March 12, 2011
  49. 49. Flushing out the initial feature list led to this much documentationSaturday, March 12, 2011
  50. 50. Flushing out the initial feature list led to this much documentationSaturday, March 12, 2011
  51. 51. Examples of how features will work are flushed outSaturday, March 12, 2011
  52. 52. Initial hurdles are identifiedSaturday, March 12, 2011
  53. 53. Some ideas are reconsideredSaturday, March 12, 2011
  54. 54. Next Step: Work through issuesSaturday, March 12, 2011
  55. 55. Next Step: Write some step-by- step instructionsSaturday, March 12, 2011
  56. 56. Rough notes Starting 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. Thats it! Now the table of contents is served at http://sitename.com/prefix/ Structure of the Documentation Sphinx 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 doesnt 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 directorys 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 pages 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 doesnt exist, do you want to create it? 4. Say Yes. 5. Start writing.Saturday, March 12, 2011
  57. 57. Rough notes Starting 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. Thats it! Now the table of contents is served at http://sitename.com/prefix/ Structure of the Documentation Sphinx 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 doesnt 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 directorys 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
  58. 58. Rough notes Starting 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. Thats it! Now the table of contents is served at http://sitename.com/prefix/ Structure of the Documentation Sphinx 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 doesnt 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 directorys 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
  59. 59. Thats it! Now the table of contents is served at http://sitename.com/prefix/ Structure of the Documentation Rough notes Sphinx 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 doesnt 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 directorys 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 pages 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 doesnt exist, do you want to create it? 4. Say Yes. 5. Start writing.Saturday, March 12, 2011
  60. 60. Write a tutorialSaturday, March 12, 2011
  61. 61. How do I…?Saturday, March 12, 2011
  62. 62. ResearchSaturday, March 12, 2011
  63. 63. In summary • Code your documentation • Make a customized documentation skeleton • Iterate over your documentation • Find a groove that works for youSaturday, March 12, 2011
  64. 64. Thank You • Corey Oordt • coreyoordt@gmail.com • http://github.com/coordt • http://github.com/washingtontimes • @coordtSaturday, March 12, 2011
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×