+1 to all (and I'd emphasize #3 as "indent with four spaces rather than
tabs *or two spaces*).
The one thing I'd clarify is that intra-page linking can still just use
a href="#...". Anyone feel like intra-page section links should go out
through site.xml?
Rich
Eddie O'Neil wrote:
All--
As several of us seem to be writing documentation, why don't we
adopt some conventions for how the doc is formatted and how documents
are named?
Suggestions:
- use camel-case for document names rather than a mix of '_', '-', and
camel case
- use camel-case for Forrest <section> identifiers
- indent with four spaces rather than tabs
- do intra-site linking through site.xml for both document links and
section links (see the <ant-macros> element in site.xml for an example
of section links)
- name documents without too much repetition. For example, I just
renamed some docs like: controls/controls_overview.xml to
controls/overview.xml.
I'd be willing to keep going through the documentation changing some
of this before ship since it makes the doc kit more consistent and
URL friendly if everyone agrees that it's the right thing to do.
Thoughts? Other suggestions?
Eddie
