suggestions for Forrest documentation formatting

[Eddie O'Neil <ek...@gmail.com>]

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

Re: suggestions for Forrest documentation formatting

[Daryl Olander <do...@gmail.com>]

+1 for this....



On 8/24/05, Eddie O'Neil <ek...@gmail.com> 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
>

Re: suggestions for Forrest documentation formatting

[Rich Feit <ri...@gmail.com>]

+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
>
>  
>