Sean Marquez capsulecorplab

Graphviz

digraph g {
    a -> b
    b -> c
    c -> d
    d -> a
}

some tools for diagrams in software documentation

Diagrams For Documentation

Obvious Choices

ASCII

Documentation-Driven Development

The philosophy behind Documentation-Driven Development is a simple: from the perspective of a user, if a feature is not documented, then it doesn't exist, and if a feature is documented incorrectly, then it's broken.

Document the feature first. Figure out how you're going to describe the feature to users; if it's not documented, it doesn't exist. Documentation is the best way to define a feature in a user's eyes.
Whenever possible, documentation should be reviewed by users (community or Spark Elite) before any development begins.
Once documentation has been written, development should commence, and test-driven development is preferred.
Unit tests should be written that test the features as described by the documentation. If the functionality ever comes out of alignment with the documentation, tests should fail.
When a feature is being modified, it should be modified documentation-first.
When documentation is modified, so should be the tests.

	# Software Requirements Specification
	## For <project name>
	Version 1.0 approved
	Prepared by <author>
	<organization>
	<date created>

	# Table of Contents
	[Table of Contents](#example)
	[Revision History](#revision-history)

	// Also available at: https://play.golang.org/p/yTTpB5gB6C

	package main

	import (
	"fmt"
	)

	// *****************************************************************************
	// Example 1 - Struct vs Struct with Embedded Type

	from __future__ import division
	import string
	import math

	tokenize = lambda doc: doc.lower().split(" ")

	document_0 = "China has a strong economy that is growing at a rapid pace. However politically it differs greatly from the US Economy."
	document_1 = "At last, China seems serious about confronting an endemic problem: domestic violence and corruption."
	document_2 = "Japan's prime minister, Shinzo Abe, is working towards healing the economic turmoil in his own country for his view on the future of his people."
	document_3 = "Vladimir Putin is working hard to fix the economy in Russia as the Ruble has tumbled."

	# Ruby is our language as asciidoctor is a ruby gem.
	lang: ruby
	before_install:
	- sudo apt-get install pandoc
	- gem install asciidoctor
	script:
	- make
	after_success:
	- .travis/push.sh
	env:

	#' Get a PubMed search index
	#' @param query a PubMed search string
	#' @return the XML declaration of the search
	#' @example
	#' # Which articles discuss the WHO FCTC?
	#' pubmed_ask("FCTC OR 'Framework Convention on Tobacco Control'")
	pubmed_ask <- function(query) {

	# change spaces to + and single-quotes to URL-friendly %22 in query
	query = gsub("'", "%22", gsub(" ", "+", query))

	"
	prototype ledger file parser in squeak
	Simon Michael

	test scripts:

	s1 := LedgerParserTests sample1 readStream
	PositionableStream
	2007/10/7 the fairmont sonoma mission inn & spa
	expenses:food:dining $11

	# -- coding: utf-8 --

	"""
	A class which defines a composit object which can store
	hierarchical dictionaries with names.

	This class is same as a hierarchical dictionary, but it
	provides method to add/accesss/modify children by name,
	like a Composit.