Sean Marquez capsulecorplab

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.

Here is a syntax cheatsheet for asciidoc -→

AsciiDoc Markup Syntax Summary

A summary of the most commonly used markup. For a complete reference see the 'AsciiDoc User Guide'.

Text formatting

This text now lives at https://github.com/MarcDiethelm/contributing/blob/master/README.md. I turned it into a Github repo so you can, you know, contribute to it by making pull requests.

Contributing

If you want to contribute to a project and make it better, your help is very welcome. Contributing is also a great way to learn more about social coding on Github, new technologies and and their ecosystems and how to make constructive, helpful bug reports, feature requests and the noblest of all contributions: a good, clean pull request.

The Ultimate Git Alias Setup

If you use git on the command-line, you'll eventually find yourself wanting aliases for your most commonly-used commands. It's incredibly useful to be able to explore your repos with only a few keystrokes that eventually get hardcoded into muscle memory.

Some people don't add aliases because they don't want to have to adjust to not having them on a remote server. Personally, I find that having aliases doesn't mean I that forget the underlying commands, and aliases provide such a massive improvement to my workflow that it would be crazy not to have them.

The simplest way to add an alias for a specific git command is to use a standard bash alias.

# .bashrc

GitHub Flavored Markdown

View the [source of this content](http://github.github.com/github-flavored-markdown/sample_content.html).

Equivalent in AsciiDoc

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