new specification template - feedback after my first spec

Hi,

currently writing my first small spec based on the new
specification
template, here's some feedback ...

- After putting the template into my OOo's template folder,
the first
  thing I saw is that it's listed with the title
  "OpenOffice-org-Specification-Template" (which
is the stripped file
  name) in the "File/New/Documents and
Templates" dialog. Would be nicer
  if we would give the file a document title in the
"File/Properties".

- "First, make sure your Proxy Settings are
correct". An additional
  explanatory sentence saying why might relief the paranoid
ones ...

- It would be cool if you could hide single help sections
separately,
  instead of all or none. I'd like to hide all the help
sections which I
  already addressed, but show the remaining ones. This would
improve
  readability while writing the document.

- Seeing the "References and Reference
Documents" section: If my spec
  interacts with other specs, I'd have to list those here
(I assume).
  Again it would be nice if specification documents had an
ID which
  could be used to refer to them in other documents. In
thise case, the
  "References" could be a mere
"Bibliography Index" (wouldn't it be cool
  to use the features Writer provides to us?), with the
document ID
  being the Bibliography identifier.

- For the "product version", which should not be
mentioned:
  Somehow I think the information to which product version
the current
  document version applies might be interesting. At least,
from reading
  the specification it should be clear when the respective
feature was
  introduced. Else, we might get a lot of "but it is
specified <here>,
  so why does my OOo x.0.y not have it?" (well,
because it's implemented
  in x.1.z only.)
  The "Product Name" placeholder might in fact
not be the appropriate
  place for this, but we should find one, IMO.
  (or, well, ehm, we should have a document management
system which can
  associate attributes with specification document
revisions, such as
  "revision a.b of document X applies to product
version x.y.z".)

- why must people use their openoffice.org address in
the "i-Team
  Members" section? 

- Why must I enter the specification title multiple times?
At least in
  the document heading, and in the page headers. Would be
better (and
  less prone to document inconsistencies) if I could just
change the
  document title in "File/Properties", and have
a field
  ("Insert/Fields/Title") reflecting this title
in all other places

- I somewhat missed a glossary, which existed in the
previous spec
  template. Is there a reason this vanished?
  I think it might still be usefull to explain terms in the
document
  which are from the problem domain, but not absolutely
obvious to every
  reader. At least to ensure that all readers really
understand the
  same, this might be highly desired (else the [R2] rule
might be hard
  to fulfill)

- The "A new version of the custom AutoText
..."-dialog (opened when you
  press the "Insert Table" button in the spec
toolbar) has a text
  overlapping its buttons.

- the "CheckForNewerAutoTexts" method sometimes
breaks with a NULL
  oStatusIndicator. Could not find out, *when*, but
sometimes it works,
  sometimes it doesn't.

- in tables describing UI elements, I'm missing a
possibility to declare
  toolbar items. That is, if my spec introduces a new
toolbar item, I
  currently don't have a defined place to declare the
English/German
  tooltip texts for this item.

- According to the help texts, incompatible configuration
settings have
  to be handled in both chapter 2 ("Migration":
"Did I specify the
  incompatible or removed configuration settings?")
and chapter 3
  ("Configuration": "If it is a new /
incompatible setting did I specify
  a migration path?"). Hmm.

- In the configuration section's table, I find the
separation into
  "Group" and "Setting"
questionable. Usually, a configuration setting
  is specified by a arbitrarily nested path, which cannot
(at least not
  canonically) be split into a group and a setting. Or is
"Group"
  intended to hold the path to the "Setting"?

- When writing a spec which includes menu/toolbar changes:
  [R1] requires that those changes are part of the
respective
  comprehensive menu/toolbar specification document.
However, I wonder
  when would be the best time to add this info there: When I
start
  writing my own specification, it might take months until
the described
  changes are really part of the product. So I cannot
reasonably change
  the global specs at this time, because people might expect
them to
  reflect to current state of the product.
  So, should I add a note to those global specs, saying
"once spec
  <my_new_spec> is implemented, this here will
change"? Should I add the
  the changes in the global spec only when my new feature is
  implemented?

- as "Revision" of the document, do we really
allow integers only? A
  numbering scheme similar to a product numbering (x.y, or
even x.y.z)
  would have the advantage that already the revision can
distinguish
  between minor and major changes. That is, if I just
correct a spelling
  error, I would increment the revision number from 3 to
3.0.1 (or so),
  if I add a new chapter, it would probably 3.1, and if I
re-write the
  complete spec, it would be 4. So, readers following the
evolution of
  the spec document might better be able to judge impact of
a new
  document revision.

Ciao
Frank

-- 
- Frank Schönheit, Software Engineer        
frank.schoenheitsun.com -
- Sun Microsystems                      http://www.sun.com/star
office -
- OpenOffice.org Database                   http://dba.openoffice.org -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - -

------------------------------------------------------------
---------
To unsubscribe, e-mail: dev-unsubscribespecs.openoffice.org
For additional commands, e-mail: dev-helpspecs.openoffice.org