moving spec files around
DOCS-2011 moving syntax examples around
DOCS-2027: adding note to clarify
minor: syntax fix