beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Feit <>
Subject Re: suggestions for Forrest documentation formatting
Date Wed, 24 Aug 2005 16:54:20 GMT
+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?


Eddie O'Neil wrote:

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

View raw message