Documentation Driven Development

Corey Oordt @coordt

Saturday, March 12, 2011

Origins

I’m writing documentation?!

What was I thinking?

http://www.onesigmaoff.net/?p=40

1. Write code2. Write documentation3. Rewrite code

1. Write code2. Write documentation12

3. Rewrite code

RANDOMSPECULATION

The great virtues of a programmer

LazinessImpatienceHubris

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

We get functional, but not useable code

Functional, not Useable

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

Writing documentation first changes your

perspective

http://www.gravestmor.com/strips/Saturday, March 12, 2011

Don’t document your code,code your documentation

Sometimes coding feels like falling down stairs and landing

on your feet

http://www.flickr.com/photos/zen/2339658529/

How do I start?

http://www.flickr.com/photos/hlkljgk/1227416397/sizes/l/in/photostream/Saturday, March 12, 2011

http://sphinx.pocoo.org/

Have a default Sphinx setup

Include your favorite template or theme

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()

import sys, os

Create placeholder and boilerplate files

doc_src

_build

_static

_templates

conf.py

getting_started.rst

index.rst

installation.rst

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."

Allows you to build docs often

See http://github.com/washingtontimes/

django-app-skeleton/

Jumping off points

http://www.flickr.com/photos/frecklefinger/1369581228/

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

* 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?

* 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?

Flushing out the initial feature list led

to this much documentation

Flushing out the initial feature list led

to this much documentation

Examples of how features will work are flushed out

Initial hurdles are identified

Some ideas are reconsidered

Next Step: Work through issues

Next Step: Write some step-by-step instructions

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.

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/

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.

Write a tutorial

How do I…?

Research

In summary

• Code your documentation

• Make a customized documentation skeleton

• Iterate over your documentation

• Find a groove that works for you

Thank You

• Corey Oordt

• coreyoordt@gmail.com

• http://github.com/coordt

• http://github.com/washingtontimes

• @coordt

Documentation Driven Development

Technology

Behaviour Driven Development

Obstacle Driven Development: Extending Test Driven Development

Documentation - Systems, software and technology · Process documentation is produced so that the development of the system can be managed and is an essential component of plan-driven

Domain driven design and model driven development

Project Documentation Gebäude-Dokumentation · Project Documentation ... The students dormitory GreenHouse in the urban development area ... on demand-driven ventilation system with

Living Documentation by design, with Domain-Driven Design

Managing Software Components with Teamcenter Enterprise ... · · Model-Driven Development · Abstraction · Automation (Code generation, testing, documentation) · Reuse (through

Behaviour-Driven Development - · PDF fileisso em código 10. ... Behaviour-Driven Development JUnit (Test::Unit) 12 Teste. Behaviour-Driven Development Especiﬁcação ... $ ruby

Derivatives regulatory driven changes to documentation... · 2020-05-25 · Derivatives – regulatory driven changes to documentation Marc Benzler, Habib Motani and Gareth Old 16/17

Overview on TDD (Test Driven Development) & ATDD (Acceptance Test Driven Development)

Acceptance Test Driven Development (ATDD) · ATDD Lineage ATDD comes from: Example driven development (EDD) Behavior-driven development (BDD) Story-driven development (SDD) Domain-driven

DANIELE PROCIDA DOCUMENTATION-DRIVEN DEVELOPMENT - … · documentation-driven development like test-driven development, puts should before is establishes a shared, easily-accessible,

Planning Driven Development Hillel Wayne · Practical TLA+ Planning Driven Development — Hillel Wayne

Test Driven Development II - Advanced · 2019-03-19 · Test Driven Development with FHIR Intro Session Review ... •Continuous Integration build processes •Documentation and example

tools for security that matters - OWASPPart 1: Cucumber & friends Test-Driven Development, Behavior-Driven Development & Beyond Test Driven Development • Veriﬁcation • Building

Miséria Driven Development

Morelia Documentation - media.readthedocs.org · Morelia Documentation, Release 0.9.0 Morelia is a Python Behavior Driven Development (BDD1) library. BDD is an agile software development

Test driven documentation

Test Driven Development

Test Driven Development II - Advanced · Test Driven Development II - Advanced Richard Ettema, AEGIS.net, Inc. Presented by ... Continuous Integration build processes Documentation