new specification template - feedback after my first spec

Hi Frank,

thanks for your feedback. Find our comments inline.

Frank Schönheit - Sun Microsystems Germany wrote On 04/21/06
14:40,:

 > - 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".

A certainly desirable enhancement. We already put that on
the list of
future enhancements.

 > - 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.
Just do it! "Writer ->
Format->Sections->Hide"

 > - 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 becool
 >   to use the features Writer provides to us?), with
the document ID
 >   being the Bibliography identifier.

Having IDs is a solution. Currently we are collecting the
problems which 
occour in the area of linking to other documents. Right now,
we can't 
say how the solution gonna look like.

 > - 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.
Of course it is.

 >   The "Product Name" placeholder might in
fact not be the appropriate
 >   place for this, but we should find one, IMO.
Feature development starts when there is a requirement or
RFE which
should be associated with a respective task in our task
tracking system.
So either this task has been directly entered into the row
"Product
Requirement, RFE, issue" or it is in the requirement
document itself.So
you should be able to track with this information into which
version of
the product a feature made it.

 >   (or, well, ehm, we should have a document management
system whichcan
 >   associate attributes with specification document
revisions, such as
 >   "revision a.b of document X applies to product
version x.y.z".)
Dream on ;)

 > - why must people use their openoffice.org address in
the "i-Team
 >   Members" section? 
Nobody must do this. But this is a template which should be
usable by
the whole OOo community ;) Should a OOo people enter a sun
address?
You're free to use your Sun or whatever address e.g. for
StarOffice only
features.

 > - Why must I enter the specification title multiple
times? At leastin
 >   the document heading, and in the page headers.
A valid wish for enhancement. We already have this on our
list.

 > - 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)
Well there is a "Acronyms and Abbreviations"
table. If this is not
sufficient
to you use a glossary as well nobody will hinder you. Do
everything that
helps making the specification clear to the intended
readership but
please don't expect that the template disburden you from
every task ;)

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

We put this on our issue list.
 >
 > - the "CheckForNewerAutoTexts" method
sometimes breaks with a NULL
 >   oStatusIndicator. Could not find out, *when*, but
sometimes it works,
 >   sometimes it doesn't.

We put this on our issue list.

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

That's true we are working on that.

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

We put this on our issue list.

 > - 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 leastnot
 >   canonically) be split into a group and a setting. Or
is "Group"
 >   intended to hold the path to the
"Setting"?
We designed this section as it is based on feedback. If you
have
suggestions
for enhancements we are interested to hear your concrete
suggestions!

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

We recommend to add the changes to the global specs when
every thing of 
the feature spec is final.

 > - 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 evolutionof
 >   the spec document might better be able to judge
impact of a new
 >   document revision.
We don't want to make things more complicated than
necessary. IMO its
not that important which revision scheme we're using. No
defects result
from this. Defects result from the fact that affected
stakeholder are
not informed about changes or that they do not know what the
changes
have been made.

The P3386 Team

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