Home » Archived » BIRT » ROM Feedback: Object Naming
| ROM Feedback: Object Naming [message #661] |
Thu, 30 December 2004 22:28  |
 Scott Rosenbaum
Messages: 425
Registered: July 2009 |
Senior Member |
|
|
Maybe it is me getting older, but I am having a bit of a hard time
understanding the naming conventions used within the ROM documentation. It
seems like a number of formal names are created by taking two very common
terms and combining them together, e.g. Report Element. I focus on Report
Element in this post, but my thoughts apply to all of the ROM objects.
As I understand it, all of the following are synonomous:
- Report Element (display name)
- report element (I don't think this should ever be used in the docs)
- ReportElement (A JavaScript Runtime Object)
- ReportElementDefn (A JavaScript DesignTime object)
If within the context of ROM a Report Element is a name for a specific item,
that is unique to the ROM world I think that it should be documented in a
way that distinguishes it from just an element in a report. So I would
prefer to see ReportElement, over Report Element (or worse report element).
I have done a bit of instruction to report developers, and I have often
found introducing new technical terms to be tricky. It seems to go better
if the term is somehow unique, it's as if the brain instinctively says "ahh
ha - ReportElement, this is something new it must be significant".
Along those lines I would prefer to see the following:
- ReportElement (display name)
- ReportElementDefn (A JavaScript DesignTime object)
- ReportElementObj (A JavaScript Runtime Object)
Scott Rosenbaum
|
|
|
| Re: ROM Feedback: Object Naming [message #1614 is a reply to message #661] |
Thu, 06 January 2005 00:57  |
Paul Rogers
Messages: 152
Registered: July 2009 |
Senior Member |
|
|
Scott,
Thanks for the feedback on ROM naming. Let me outline our thinking and let's
see if we can work out a better solution.
Every item in ROM has a formal name in the XML schema and in the internal
"model" stored in the Design Engine (accessible via the "DE API"). This name
must follow the XML and JavaScript naming rules. In particular, it can't
have spaces. Hence "ReportElement".
Some people (myself included) find docs full of identifiers hard to read.
So, every element also has an "English name" (display name) to make the
document flow easier: "Report Element." The general rule is that the display
name should be used in docs, UI, e-mail, etc. The internal name need only be
used in examples, code, etc.
Internationalizion is a key BIRT goal. The "display name" can be localized,
but the formal name cannot be. Hence, we can translate "Data Item", "Text
Item" and "Data Set" into Chinese, German, Spanish, etc. But, we cannot
translate the identifiers (formal names.)
Further, display names make proofreading of documents easier because we are
not inventing a bunch of new words; we're just using English terms.
We do need to work out if the docs should capitalize the display name:
"Report Element" or "report element". Once the decision is made, we should
be consistent. For example, when writing a tutorial, should I say, "Next,
create a Label and set its Color", or "Next, create a label and set its
color." (I prefer the latter; it is more natural.) And, either of these are
better, IMHO, to "Next, create a LabelItem and set its textColor" as one
often sees in programming books.
Also, the names were chosen so that if you were to use a generic phase such
as "report item", or "label" or "color", it would pretty much correspond to
an identical formal name.
So far everything is simple because we're talking about the design-time
representation. If we have, say, a Label, then we have only one design-time
instance of each label (Label?) we create. (See, there is the case issue
again.) But, at runtime, there is that old one-to-many issue that has
confused so many Actuate e.RD-Pro users over the years: we don't have just
one label, we may have hundreds. We designed one "Customer Name:" label, but
I may have 20 per page in the actual report.
Hence, the need for two JavaScript objects. We elected to call the
"instance" the same name as the element: "Label". We chose to expose the
design time state as a different object with a different name: "LabelDefn"
(to be changed to "LabelDesign".) Now, we can't really combine the two
without giving up the distinction between design info and instance. Perhaps
we could add a suffix to the state, as you suggest: "LabelInstance" or
"LabelObject"? (I dislike "Object" because there are now different kinds of
object. One would have to understand the difference between a "JavaScript
object" [such as LabelDefn] and a report object such as LabelObject...)
Since the goal of all of this is to make the system easier to describe, your
feedback on training is very useful. Do you think the possible costs in
confusion of using English names outweigh the benefits of not using
identifiers for everything? For example: "OK, now set the background color
of your text item" vs. "OK, now set the backgroundColor of your TextItem".
Also, the UI would show "TextItem" in the palette vs. "Text Item". And
French, German, Spanish, Chinese and other users would also see "TextItem"
instead of the translated equivalent of the term "text item". Do you think a
non-English speaking student would prefer text with translated words for
"background color" and "text item", or would they prefer text with the
formal English names?
What do you think?
- Paul
Paul Rogers
Actuate Corp.
BIRT PMC
|
|
|
| Re: ROM Feedback: Object Naming [message #1703 is a reply to message #1614] |
Sat, 08 January 2005 16:50 |
Scott Rosenbaum
Messages: 425
Registered: July 2009 |
Senior Member |
|
|
This is a multi-part message in MIME format.
------=_NextPart_000_0025_01C4F56F.EFBB21D0
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Paul,
Its clear you all have spent a lot of time thinking this through. I =
agree with you that it is easier to read "Next, create a label and set =
its color." That said, when doing instruction I find that getting =
people to engage on content and clarity of terms are the most important =
things. I would like to get the opinions of some other people that are =
monitoring this newsgroup. =20
As I understand the ROM a BIRT report has the following hierarchy of =
elements:
Design Element (which contain)
Report Element (which contain)
Data Source
Data Set
Report Item (which contain)
Label Item (which have a)
text Color property
So I am going to attempt a simple paragraph that describes the relations =
of these elements using three naming styles, I will start with the most =
natural form, move to a bit more formal style using natural language =
with unique capitalization to highlight the unique BIRT terms. Finally, =
I will use a style that uses unique formal names for the elements in the =
ROM.
Lower Case Naming
BIRT reports are created through the assembly of components. At the =
base of every report is the design element. Design elements can contain =
one or more report elements. Each report element consists of a data =
source which will populate a data set. The report element passes the =
data set to a report item which will create the visual representation of =
the data set. Report items are made up of label items, data items, list =
items, or graphic items which take care of the visual display of the =
data set.
Upper Case Naming
BIRT reports are created through the assembly of components. At the =
base of every report is the Design Element. Design Elements can contain =
one or more Report Elements. Each Report Element consists of a Data =
Source which will populate a Data Set. The Report Element passes the =
Data Set to a Report Item which will create the visual representation of =
the Data Set. Report Items are made up of Label Items, Data Items, List =
Items, or Graphic Items which take care of the visual display of the =
Data Set.
Upper Case No Space Naming
BIRT reports are created through the assembly of components. At the =
base of every report is the DesignElement. DesignElements can contain =
one or more ReportElements. Each ReportElement consists of a DataSource =
which will populate a DataSet. The ReportElement passes the DataSet to =
a ReportItem which will create the visual representation of the DataSet. =
ReportItems are made up of LabelItems, DataItems, ListItems, or =
GraphicItems which take care of the visual display of the DataSet.
I realize that the paragraph needs a bit of word smithing, and is not =
quite ready for the help documents yet. That said, I would be interest =
to see what other people think of a side by side comparison.=20
I can work with either style, I think the key issue is to use =
consistency. Just for grins, I have taken the lower case example and =
done it one more time, this time leaving out some of the full names of =
the components. This is the type of lose naming that can make learning =
a new product really maddening. It is easy to read, it is just a bit =
misleading.
Lower Case Inconsistent Naming
BIRT reports are created through the assembly of components. At the =
base of every report is the design element. Designs can contain one or =
more report elements. Each report element consists of a data source =
which will populate a data set. The report passes the data to a report =
item which will create the visual representation of the data set. =
Report items are made up of label items, data items, list items, or =
graphic items which take care of the visual display of the data. =20
As to the internationalization, you make some very good points but I =
would prefer to get some feedback from developers that are not using =
English as their primary language. =20
Scott Rosenbaum
"Paul Rogers" <progers@actuate.com> wrote in message =
news:cri2f7$rll$1@www.eclipse.org...
> Scott,
>=20
> Thanks for the feedback on ROM naming. Let me outline our thinking and =
let's=20
> see if we can work out a better solution.
>=20
> Every item in ROM has a formal name in the XML schema and in the =
internal=20
> "model" stored in the Design Engine (accessible via the "DE API"). =
This name=20
> must follow the XML and JavaScript naming rules. In particular, it =
can't=20
> have spaces. Hence "ReportElement".
>=20
> Some people (myself included) find docs full of identifiers hard to =
read.=20
> So, every element also has an "English name" (display name) to make =
the=20
> document flow easier: "Report Element." The general rule is that the =
display=20
> name should be used in docs, UI, e-mail, etc. The internal name need =
only be=20
> used in examples, code, etc.
>=20
> Internationalizion is a key BIRT goal. The "display name" can be =
localized,=20
> but the formal name cannot be. Hence, we can translate "Data Item", =
"Text=20
> Item" and "Data Set" into Chinese, German, Spanish, etc. But, we =
cannot=20
> translate the identifiers (formal names.)
>=20
> Further, display names make proofreading of documents easier because =
we are=20
> not inventing a bunch of new words; we're just using English terms.
>=20
> We do need to work out if the docs should capitalize the display name: =
> "Report Element" or "report element". Once the decision is made, we =
should=20
> be consistent. For example, when writing a tutorial, should I say, =
"Next,=20
> create a Label and set its Color", or "Next, create a label and set =
its=20
> color." (I prefer the latter; it is more natural.) And, either of =
these are=20
> better, IMHO, to "Next, create a LabelItem and set its textColor" as =
one=20
> often sees in programming books.
>=20
> Also, the names were chosen so that if you were to use a generic phase =
such=20
> as "report item", or "label" or "color", it would pretty much =
correspond to=20
> an identical formal name.
>=20
> So far everything is simple because we're talking about the =
design-time=20
> representation. If we have, say, a Label, then we have only one =
design-time=20
> instance of each label (Label?) we create. (See, there is the case =
issue=20
> again.) But, at runtime, there is that old one-to-many issue that has=20
> confused so many Actuate e.RD-Pro users over the years: we don't have =
just=20
> one label, we may have hundreds. We designed one "Customer Name:" =
label, but=20
> I may have 20 per page in the actual report.
>=20
> Hence, the need for two JavaScript objects. We elected to call the=20
> "instance" the same name as the element: "Label". We chose to expose =
the=20
> design time state as a different object with a different name: =
"LabelDefn"=20
> (to be changed to "LabelDesign".) Now, we can't really combine the two =
> without giving up the distinction between design info and instance. =
Perhaps=20
> we could add a suffix to the state, as you suggest: "LabelInstance" or =
> "LabelObject"? (I dislike "Object" because there are now different =
kinds of=20
> object. One would have to understand the difference between a =
"JavaScript=20
> object" [such as LabelDefn] and a report object such as =
LabelObject...)
>=20
> Since the goal of all of this is to make the system easier to =
describe, your=20
> feedback on training is very useful. Do you think the possible costs =
in=20
> confusion of using English names outweigh the benefits of not using=20
> identifiers for everything? For example: "OK, now set the background =
color=20
> of your text item" vs. "OK, now set the backgroundColor of your =
TextItem".=20
> Also, the UI would show "TextItem" in the palette vs. "Text Item". And =
> French, German, Spanish, Chinese and other users would also see =
"TextItem"=20
> instead of the translated equivalent of the term "text item". Do you =
think a=20
> non-English speaking student would prefer text with translated words =
for=20
> "background color" and "text item", or would they prefer text with the =
> formal English names?
>=20
> What do you think?
>=20
> - Paul
>=20
> Paul Rogers
> Actuate Corp.
> BIRT PMC=20
>=20
>
------=_NextPart_000_0025_01C4F56F.EFBB21D0
Content-Type: text/html;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=3DContent-Type content=3D"text/html; =
charset=3Diso-8859-1">
<META content=3D"MSHTML 6.00.2800.1479" name=3DGENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY>
<DIV><FONT face=3DArial size=3D2>Paul,</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Its clear you all have spent a lot of =
time thinking=20
this through. I agree with you that it is easier to read "Next, =
create a=20
label and set its color." That said, when doing instruction I =
find=20
that getting people to engage on content and clarity of terms are the =
most=20
important things. I would like to get the opinions of some other =
people=20
that are monitoring this newsgroup. </FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT><FONT face=3DArial =
size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>As I understand the ROM a BIRT report =
has the=20
following hierarchy of elements:</FONT></DIV>
<DIV><FONT face=3DArial size=3D2>Design Element (which =
contain)</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> Report Element =
(which=20
contain)</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
Data=20
Source</FONT></DIV>
<DIV><FONT face=3DArial =
size=3D2> Data=20
Set</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
Report Item=20
(which contain)</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =20
Label Item (which have a)</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =20
text Color property</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>So I am going to attempt a simple =
paragraph that=20
describes the relations of these elements using three =
naming styles, I=20
will start with the most natural form, move to a bit more formal style =
using=20
natural language with unique capitalization to highlight the unique BIRT =
terms. Finally, I will use a style that uses unique formal names =
for the=20
elements in the ROM.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2></FONT><FONT face=3DArial =
size=3D2><U>Lower=20
Case Naming</U></FONT></DIV>
<DIV><FONT face=3DArial size=3D2>BIRT reports are created through the =
assembly of=20
components. At the base of every report is the design =
element. =20
Design elements can contain one or more report elements. Each =
report=20
element consists of a data source which will populate a data set. =
The=20
report element passes the data set to a report item which will create =
the visual=20
representation of the data set. Report items are made up of label =
items,=20
data items, list items, or graphic items which take care of the visual =
display=20
of the data set.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>
<DIV><FONT face=3DArial size=3D2></FONT><FONT face=3DArial =
size=3D2><U>Upper=20
Case Naming</U></FONT></DIV>
<DIV><FONT face=3DArial size=3D2>BIRT reports are created through the =
assembly of=20
components. At the base of every report is the Design =
Element. =20
Design Elements can contain one or more Report Elements. Each =
Report=20
Element consists of a Data Source which will populate a Data Set. =
The=20
Report Element passes the Data Set to a Report Item which will create =
the visual=20
representation of the Data Set. Report Items are made up of Label =
Items,=20
Data Items, List Items, or Graphic Items which take care of the visual =
display=20
of the Data Set.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2>
<DIV><FONT face=3DArial size=3D2></FONT><FONT face=3DArial=20
size=3D2><U></U></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2><U>Upper Case No Space=20
Naming</U></FONT></DIV>
<DIV><FONT face=3DArial size=3D2>
<DIV><FONT face=3DArial size=3D2>BIRT reports are created through the =
assembly of=20
components. At the base of every report is the =
DesignElement. =20
DesignElements can contain one or more ReportElements. Each =
ReportElement=20
consists of a DataSource which will populate a DataSet. The =
ReportElement=20
passes the DataSet to a ReportItem which will create the visual =
representation=20
of the DataSet. ReportItems are made up of LabelItems, DataItems,=20
ListItems, or GraphicItems which take care of the visual display of the=20
DataSet.</FONT></DIV>
<DIV> </DIV>
<DIV> </DIV>
<DIV>I realize that the paragraph needs a bit of word smithing, and is =
not quite=20
ready for the help documents yet. That said, I would be interest =
to see=20
what other people think of a side by side comparison. </DIV>
<DIV> </DIV>
<DIV>I can work with either style, I think the key issue is to use=20
consistency. Just for grins, I have taken the lower case =
example and=20
done it one more time, this time leaving out some of the full names =
of the=20
components. This is the type of lose naming that can make learning =
a new=20
product really maddening. It is easy to read, it is just a bit=20
misleading.</DIV>
<DIV> </DIV>
<DIV>
<DIV><FONT face=3DArial size=3D2></FONT><FONT face=3DArial =
size=3D2><U>Lower=20
Case Inconsistent Naming</U></FONT></DIV>
<DIV><FONT face=3DArial size=3D2>BIRT reports are created through the =
assembly of=20
components. At the base of every report is the design =
element. =20
Designs can contain one or more report elements. Each report =
element=20
consists of a data source which will populate a data set. The=20
report passes the data to a report item which will create the =
visual=20
representation of the data set. Report items are made up of =
label=20
items, data items, list items, or graphic items which take care of the =
visual=20
display of the data.</FONT> </DIV></DIV>
<DIV> </DIV>
<DIV>As to the internationalization, you make some very good points but =
I would=20
prefer to get some feedback from developers that are not using English =
as their=20
primary language. </DIV>
<DIV> </DIV>
<DIV>Scott Rosenbaum</DIV>
<DIV> </DIV>
<DIV> </DIV></FONT><FONT face=3DArial=20
size=3D2></FONT></DIV></FONT></DIV></FONT></DIV>
<DIV><FONT face=3DArial size=3D2>"Paul Rogers" <</FONT><A=20
href=3D"mailto:progers@actuate.com"><FONT face=3DArial=20
size=3D2>progers@actuate.com</FONT></A><FONT face=3DArial size=3D2>> =
wrote in=20
message </FONT><A href=3D"news:cri2f7$rll$1@www.eclipse.org"><FONT =
face=3DArial=20
size=3D2>news:cri2f7$rll$1@www.eclipse.org</FONT></A><FONT face=3DArial=20
size=3D2>...</FONT></DIV><FONT face=3DArial size=3D2>> Scott,<BR>> =
<BR>>=20
Thanks for the feedback on ROM naming. Let me outline our thinking and =
let's=20
<BR>> see if we can work out a better solution.<BR>> <BR>> =
Every item=20
in ROM has a formal name in the XML schema and in the internal <BR>> =
"model"=20
stored in the Design Engine (accessible via the "DE API"). This name =
<BR>>=20
must follow the XML and JavaScript naming rules. In particular, it can't =
<BR>> have spaces. Hence "ReportElement".<BR>> <BR>> Some =
people=20
(myself included) find docs full of identifiers hard to read. <BR>> =
So, every=20
element also has an "English name" (display name) to make the <BR>> =
document=20
flow easier: "Report Element." The general rule is that the display =
<BR>>=20
name should be used in docs, UI, e-mail, etc. The internal name need =
only be=20
<BR>> used in examples, code, etc.<BR>> <BR>> =
Internationalizion is a=20
key BIRT goal. The "display name" can be localized, <BR>> but the =
formal name=20
cannot be. Hence, we can translate "Data Item", "Text <BR>> Item" and =
"Data=20
Set" into Chinese, German, Spanish, etc. But, we cannot <BR>> =
translate the=20
identifiers (formal names.)<BR>> <BR>> Further, display names make =
proofreading of documents easier because we are <BR>> not inventing a =
bunch=20
of new words; we're just using English terms.<BR>> <BR>> We do =
need to=20
work out if the docs should capitalize the display name: <BR>> =
"Report=20
Element" or "report element". Once the decision is made, we should =
<BR>> be=20
consistent. For example, when writing a tutorial, should I say, "Next, =
<BR>>=20
create a Label and set its Color", or "Next, create a label and set its =
<BR>>=20
color." (I prefer the latter; it is more natural.) And, either of these =
are=20
<BR>> better, IMHO, to "Next, create a LabelItem and set its =
textColor" as=20
one <BR>> often sees in programming books.<BR>> <BR>> Also, the =
names=20
were chosen so that if you were to use a generic phase such <BR>> as =
"report=20
item", or "label" or "color", it would pretty much correspond to =
<BR>> an=20
identical formal name.<BR>> <BR>> So far everything is simple =
because=20
we're talking about the design-time <BR>> representation. If we have, =
say, a=20
Label, then we have only one design-time <BR>> instance of each label =
(Label?) we create. (See, there is the case issue <BR>> again.) But, =
at=20
runtime, there is that old one-to-many issue that has <BR>> confused =
so many=20
Actuate e.RD-Pro users over the years: we don't have just <BR>> one =
label, we=20
may have hundreds. We designed one "Customer Name:" label, but <BR>> =
I may=20
have 20 per page in the actual report.<BR>> <BR>> Hence, the need =
for two=20
JavaScript objects. We elected to call the <BR>> "instance" the same =
name as=20
the element: "Label". We chose to expose the <BR>> design time state =
as a=20
different object with a different name: "LabelDefn" <BR>> (to be =
changed to=20
"LabelDesign".) Now, we can't really combine the two <BR>> without =
giving up=20
the distinction between design info and instance. Perhaps <BR>> we =
could add=20
a suffix to the state, as you suggest: "LabelInstance" or <BR>>=20
"LabelObject"? (I dislike "Object" because there are now different kinds =
of=20
<BR>> object. One would have to understand the difference between a=20
"JavaScript <BR>> object" [such as LabelDefn] and a report object =
such as=20
LabelObject...)<BR>> <BR>> Since the goal of all of this is to =
make the=20
system easier to describe, your <BR>> feedback on training is very =
useful. Do=20
you think the possible costs in <BR>> confusion of using English =
names=20
outweigh the benefits of not using <BR>> identifiers for everything? =
For=20
example: "OK, now set the background color <BR>> of your text item" =
vs. "OK,=20
now set the backgroundColor of your TextItem". <BR>> Also, the UI =
would show=20
"TextItem" in the palette vs. "Text Item". And <BR>> French, German, =
Spanish,=20
Chinese and other users would also see "TextItem" <BR>> instead of =
the=20
translated equivalent of the term "text item". Do you think a <BR>>=20
non-English speaking student would prefer text with translated words for =
<BR>> "background color" and "text item", or would they prefer text =
with the=20
<BR>> formal English names?<BR>> <BR>> What do you =
think?<BR>>=20
<BR>> - Paul<BR>> <BR>> Paul Rogers<BR>> =
Actuate=20
Corp.<BR>> BIRT PMC <BR>> <BR>> </FONT></BODY></HTML>
------=_NextPart_000_0025_01C4F56F.EFBB21D0--
|
|
|
| Re: ROM Feedback: Object Naming [message #2771 is a reply to message #1703] |
Tue, 11 January 2005 12:22 |
Francois-Xavier Le Louarn
Messages: 8
Registered: July 2009 |
Junior Member |
|
|
Hi there,
I think there are two different issues that are being tackled here: on
one side, we're talking about technical users / developers and how the
doc should be written so they can quickly understand the concepts; on
the other side, there are users with a UI and step-by-step tutorials,
user guides, etc.
a) I think the technical documentation should only focus on
understandability and uniformity; internationalization is not an issue
there. My experience is that when two french developers (for instance)
speak together it's a mix of french (verbs, adjectives, etc.) and
technical language, be it german, english, french, etc. When the BIRT
technical doc is translated (I'd rather say "if it's translated"), I bet
the translation will keep the english terms.
b) Concerning the UI and the end-user documentation, then it's
different. A tutorial will use the same terminology as the UI which will
probably be lowercase. And the documentation will probably italicize the
terms to be clicked and dragged so they are rapidly identified in the text.
When applied to BIRT, I would say to go for Upper Case No Space Naming
in technical documentation but maybe I've been Java programming too
long. Or maybe I'm too much of an engineer. I think there is indeed what
Scott calls a brain declic when someone sees a weird word like
ReportElement. It reminds me of a joke: "You might be an engineer if...".
FX.
Scott Rosenbaum a écrit :
> Paul,
>
> Its clear you all have spent a lot of time thinking this through. I
> agree with you that it is easier to read "Next, create a label and set
> its color." That said, when doing instruction I find that getting
> people to engage on content and clarity of terms are the most important
> things. I would like to get the opinions of some other people that are
> monitoring this newsgroup.
>
> As I understand the ROM a BIRT report has the following hierarchy of
> elements:
> Design Element (which contain)
> Report Element (which contain)
> Data Source
> Data Set
> Report Item (which contain)
> Label Item (which have a)
> text Color property
>
> So I am going to attempt a simple paragraph that describes the relations
> of these elements using three naming styles, I will start with the most
> natural form, move to a bit more formal style using natural language
> with unique capitalization to highlight the unique BIRT terms. Finally,
> I will use a style that uses unique formal names for the elements in the
> ROM.
>
> _Lower Case Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the design element. Design elements can contain
> one or more report elements. Each report element consists of a data
> source which will populate a data set. The report element passes the
> data set to a report item which will create the visual representation of
> the data set. Report items are made up of label items, data items, list
> items, or graphic items which take care of the visual display of the
> data set.
>
> _Upper Case Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the Design Element. Design Elements can contain
> one or more Report Elements. Each Report Element consists of a Data
> Source which will populate a Data Set. The Report Element passes the
> Data Set to a Report Item which will create the visual representation of
> the Data Set. Report Items are made up of Label Items, Data Items, List
> Items, or Graphic Items which take care of the visual display of the
> Data Set.
> __
> _Upper Case No Space Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the DesignElement. DesignElements can contain
> one or more ReportElements. Each ReportElement consists of a DataSource
> which will populate a DataSet. The ReportElement passes the DataSet to
> a ReportItem which will create the visual representation of the
> DataSet. ReportItems are made up of LabelItems, DataItems, ListItems,
> or GraphicItems which take care of the visual display of the DataSet.
>
>
> I realize that the paragraph needs a bit of word smithing, and is not
> quite ready for the help documents yet. That said, I would be interest
> to see what other people think of a side by side comparison.
>
> I can work with either style, I think the key issue is to use
> consistency. Just for grins, I have taken the lower case example and
> done it one more time, this time leaving out some of the full names of
> the components. This is the type of lose naming that can make learning
> a new product really maddening. It is easy to read, it is just a bit
> misleading.
>
> _Lower Case Inconsistent Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the design element. Designs can contain one or
> more report elements. Each report element consists of a data source
> which will populate a data set. The report passes the data to a report
> item which will create the visual representation of the data set.
> Report items are made up of label items, data items, list items, or
> graphic items which take care of the visual display of the data.
>
> As to the internationalization, you make some very good points but I
> would prefer to get some feedback from developers that are not using
> English as their primary language.
>
> Scott Rosenbaum
|
|
|
| Re: ROM Feedback: Object Naming [message #3002 is a reply to message #1703] |
Fri, 14 January 2005 23:28 |
Eclipse User |
|
|
|
Originally posted by: sschafer.innoventsolutions.com
I'll just chime in here to say that consistent naming is important right
now in order to navigate the existing documentation. The only practical
way to use the docs right now is to search for things, but that's hard
to do if you don't know the right name to search for.
Speaking of documentation, I think it would be really nice to have a
web-based javadocs like documentation set for the ROM. Something where
you could search for elements and link to properties, contents, etc.
Something with a quick summary of all the properties at the top and more
detailed explainations below.
Scott Rosenbaum wrote:
> Paul,
>
> Its clear you all have spent a lot of time thinking this through. I
> agree with you that it is easier to read "Next, create a label and set
> its color." That said, when doing instruction I find that getting
> people to engage on content and clarity of terms are the most important
> things. I would like to get the opinions of some other people that are
> monitoring this newsgroup.
>
> As I understand the ROM a BIRT report has the following hierarchy of
> elements:
> Design Element (which contain)
> Report Element (which contain)
> Data Source
> Data Set
> Report Item (which contain)
> Label Item (which have a)
> text Color property
>
> So I am going to attempt a simple paragraph that describes the relations
> of these elements using three naming styles, I will start with the most
> natural form, move to a bit more formal style using natural language
> with unique capitalization to highlight the unique BIRT terms. Finally,
> I will use a style that uses unique formal names for the elements in the
> ROM.
>
> _Lower Case Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the design element. Design elements can contain
> one or more report elements. Each report element consists of a data
> source which will populate a data set. The report element passes the
> data set to a report item which will create the visual representation of
> the data set. Report items are made up of label items, data items, list
> items, or graphic items which take care of the visual display of the
> data set.
>
> _Upper Case Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the Design Element. Design Elements can contain
> one or more Report Elements. Each Report Element consists of a Data
> Source which will populate a Data Set. The Report Element passes the
> Data Set to a Report Item which will create the visual representation of
> the Data Set. Report Items are made up of Label Items, Data Items, List
> Items, or Graphic Items which take care of the visual display of the
> Data Set.
> __
> _Upper Case No Space Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the DesignElement. DesignElements can contain
> one or more ReportElements. Each ReportElement consists of a DataSource
> which will populate a DataSet. The ReportElement passes the DataSet to
> a ReportItem which will create the visual representation of the
> DataSet. ReportItems are made up of LabelItems, DataItems, ListItems,
> or GraphicItems which take care of the visual display of the DataSet.
>
>
> I realize that the paragraph needs a bit of word smithing, and is not
> quite ready for the help documents yet. That said, I would be interest
> to see what other people think of a side by side comparison.
>
> I can work with either style, I think the key issue is to use
> consistency. Just for grins, I have taken the lower case example and
> done it one more time, this time leaving out some of the full names of
> the components. This is the type of lose naming that can make learning
> a new product really maddening. It is easy to read, it is just a bit
> misleading.
>
> _Lower Case Inconsistent Naming_
> BIRT reports are created through the assembly of components. At the
> base of every report is the design element. Designs can contain one or
> more report elements. Each report element consists of a data source
> which will populate a data set. The report passes the data to a report
> item which will create the visual representation of the data set.
> Report items are made up of label items, data items, list items, or
> graphic items which take care of the visual display of the data.
>
> As to the internationalization, you make some very good points but I
> would prefer to get some feedback from developers that are not using
> English as their primary language.
>
> Scott Rosenbaum
>
>
> "Paul Rogers" <progers@actuate.com <mailto:progers@actuate.com>> wrote
> in message news:cri2f7$rll$1@www.eclipse.org...
> > Scott,
> >
> > Thanks for the feedback on ROM naming. Let me outline our thinking
> and let's
> > see if we can work out a better solution.
> >
> > Every item in ROM has a formal name in the XML schema and in the
> internal
> > "model" stored in the Design Engine (accessible via the "DE API").
> This name
> > must follow the XML and JavaScript naming rules. In particular, it can't
> > have spaces. Hence "ReportElement".
> >
> > Some people (myself included) find docs full of identifiers hard to
> read.
> > So, every element also has an "English name" (display name) to make the
> > document flow easier: "Report Element." The general rule is that the
> display
> > name should be used in docs, UI, e-mail, etc. The internal name need
> only be
> > used in examples, code, etc.
> >
> > Internationalizion is a key BIRT goal. The "display name" can be
> localized,
> > but the formal name cannot be. Hence, we can translate "Data Item",
> "Text
> > Item" and "Data Set" into Chinese, German, Spanish, etc. But, we cannot
> > translate the identifiers (formal names.)
> >
> > Further, display names make proofreading of documents easier because
> we are
> > not inventing a bunch of new words; we're just using English terms.
> >
> > We do need to work out if the docs should capitalize the display name:
> > "Report Element" or "report element". Once the decision is made, we
> should
> > be consistent. For example, when writing a tutorial, should I say,
> "Next,
> > create a Label and set its Color", or "Next, create a label and set its
> > color." (I prefer the latter; it is more natural.) And, either of
> these are
> > better, IMHO, to "Next, create a LabelItem and set its textColor" as one
> > often sees in programming books.
> >
> > Also, the names were chosen so that if you were to use a generic
> phase such
> > as "report item", or "label" or "color", it would pretty much
> correspond to
> > an identical formal name.
> >
> > So far everything is simple because we're talking about the design-time
> > representation. If we have, say, a Label, then we have only one
> design-time
> > instance of each label (Label?) we create. (See, there is the case issue
> > again.) But, at runtime, there is that old one-to-many issue that has
> > confused so many Actuate e.RD-Pro users over the years: we don't have
> just
> > one label, we may have hundreds. We designed one "Customer Name:"
> label, but
> > I may have 20 per page in the actual report.
> >
> > Hence, the need for two JavaScript objects. We elected to call the
> > "instance" the same name as the element: "Label". We chose to expose the
> > design time state as a different object with a different name:
> "LabelDefn"
> > (to be changed to "LabelDesign".) Now, we can't really combine the two
> > without giving up the distinction between design info and instance.
> Perhaps
> > we could add a suffix to the state, as you suggest: "LabelInstance" or
> > "LabelObject"? (I dislike "Object" because there are now different
> kinds of
> > object. One would have to understand the difference between a
> "JavaScript
> > object" [such as LabelDefn] and a report object such as LabelObject...)
> >
> > Since the goal of all of this is to make the system easier to
> describe, your
> > feedback on training is very useful. Do you think the possible costs in
> > confusion of using English names outweigh the benefits of not using
> > identifiers for everything? For example: "OK, now set the background
> color
> > of your text item" vs. "OK, now set the backgroundColor of your
> TextItem".
> > Also, the UI would show "TextItem" in the palette vs. "Text Item". And
> > French, German, Spanish, Chinese and other users would also see
> "TextItem"
> > instead of the translated equivalent of the term "text item". Do you
> think a
> > non-English speaking student would prefer text with translated words for
> > "background color" and "text item", or would they prefer text with the
> > formal English names?
> >
> > What do you think?
> >
> > - Paul
> >
> > Paul Rogers
> > Actuate Corp.
> > BIRT PMC
> >
> >
|
|
|
| Re: ROM Feedback: Object Naming [message #4216 is a reply to message #3002] |
Wed, 19 January 2005 06:04 |
Paul Rogers
Messages: 152
Registered: July 2009 |
Senior Member |
|
|
Steve,
The idea of a web-based Javadoc-like set of docs for BIRT is a good one.
Anyone know of a tool to generate this kind of documentation from documents
insead of Java code?
As we move forward, we'll add more documentation, and do plan to add a
search facility of some sort.
Also, the ROM material will likely be easier to digest once the BIRT
designer is available to play with. At that point, the ROM specs will be
more of a supplemental reference. At the moment, we're in an awkward phase
in which the ROM specs are your primary means for learning about BIRT.
- Paul
Paul Rogers
BIRT Evangelist
Actuate Corp.
BIRT PMC
"Steve Schafer" <sschafer@innoventsolutions.com> wrote in message
news:cs9kk3$19g$1@www.eclipse.org...
> I'll just chime in here to say that consistent naming is important right
> now in order to navigate the existing documentation. The only practical
> way to use the docs right now is to search for things, but that's hard to
> do if you don't know the right name to search for.
>
> Speaking of documentation, I think it would be really nice to have a
> web-based javadocs like documentation set for the ROM. Something where
> you could search for elements and link to properties, contents, etc.
> Something with a quick summary of all the properties at the top and more
> detailed explainations below.
>
> Scott Rosenbaum wrote:
>> Paul,
>> Its clear you all have spent a lot of time thinking this through. I
>> agree with you that it is easier to read "Next, create a label and set
>> its color." That said, when doing instruction I find that getting people
>> to engage on content and clarity of terms are the most important things.
>> I would like to get the opinions of some other people that are monitoring
>> this newsgroup. As I understand the ROM a BIRT report has the following
>> hierarchy of elements:
>> Design Element (which contain)
>> Report Element (which contain)
>> Data Source
>> Data Set
>> Report Item (which contain)
>> Label Item (which have a)
>> text Color property
>> So I am going to attempt a simple paragraph that describes the relations
>> of these elements using three naming styles, I will start with the most
>> natural form, move to a bit more formal style using natural language with
>> unique capitalization to highlight the unique BIRT terms. Finally, I
>> will use a style that uses unique formal names for the elements in the
>> ROM.
>> _Lower Case Naming_
>> BIRT reports are created through the assembly of components. At the base
>> of every report is the design element. Design elements can contain one
>> or more report elements. Each report element consists of a data source
>> which will populate a data set. The report element passes the data set
>> to a report item which will create the visual representation of the data
>> set. Report items are made up of label items, data items, list items, or
>> graphic items which take care of the visual display of the data set.
>> _Upper Case Naming_
>> BIRT reports are created through the assembly of components. At the base
>> of every report is the Design Element. Design Elements can contain one
>> or more Report Elements. Each Report Element consists of a Data Source
>> which will populate a Data Set. The Report Element passes the Data Set
>> to a Report Item which will create the visual representation of the Data
>> Set. Report Items are made up of Label Items, Data Items, List Items, or
>> Graphic Items which take care of the visual display of the Data Set.
>> __ _Upper Case No Space Naming_
>> BIRT reports are created through the assembly of components. At the base
>> of every report is the DesignElement. DesignElements can contain one or
>> more ReportElements. Each ReportElement consists of a DataSource which
>> will populate a DataSet. The ReportElement passes the DataSet to a
>> ReportItem which will create the visual representation of the DataSet.
>> ReportItems are made up of LabelItems, DataItems, ListItems, or
>> GraphicItems which take care of the visual display of the DataSet.
>> I realize that the paragraph needs a bit of word smithing, and is not
>> quite ready for the help documents yet. That said, I would be interest
>> to see what other people think of a side by side comparison.
>> I can work with either style, I think the key issue is to use
>> consistency. Just for grins, I have taken the lower case example and
>> done it one more time, this time leaving out some of the full names of
>> the components. This is the type of lose naming that can make learning a
>> new product really maddening. It is easy to read, it is just a bit
>> misleading.
>> _Lower Case Inconsistent Naming_
>> BIRT reports are created through the assembly of components. At the base
>> of every report is the design element. Designs can contain one or more
>> report elements. Each report element consists of a data source which
>> will populate a data set. The report passes the data to a report item
>> which will create the visual representation of the data set. Report
>> items are made up of label items, data items, list items, or graphic
>> items which take care of the visual display of the data. As to the
>> internationalization, you make some very good points but I would prefer
>> to get some feedback from developers that are not using English as their
>> primary language. Scott Rosenbaum
>> "Paul Rogers" <progers@actuate.com <mailto:progers@actuate.com>> wrote
>> in message news:cri2f7$rll$1@www.eclipse.org...
>> > Scott,
>> >
>> > Thanks for the feedback on ROM naming. Let me outline our thinking and
>> let's
>> > see if we can work out a better solution.
>> >
>> > Every item in ROM has a formal name in the XML schema and in the
>> internal
>> > "model" stored in the Design Engine (accessible via the "DE API").
>> This name
>> > must follow the XML and JavaScript naming rules. In particular, it
>> can't
>> > have spaces. Hence "ReportElement".
>> >
>> > Some people (myself included) find docs full of identifiers hard to
>> read.
>> > So, every element also has an "English name" (display name) to make
>> the
>> > document flow easier: "Report Element." The general rule is that the
>> display
>> > name should be used in docs, UI, e-mail, etc. The internal name need
>> only be
>> > used in examples, code, etc.
>> >
>> > Internationalizion is a key BIRT goal. The "display name" can be
>> localized,
>> > but the formal name cannot be. Hence, we can translate "Data Item",
>> "Text
>> > Item" and "Data Set" into Chinese, German, Spanish, etc. But, we
>> cannot
>> > translate the identifiers (formal names.)
>> >
>> > Further, display names make proofreading of documents easier because
>> we are
>> > not inventing a bunch of new words; we're just using English terms.
>> >
>> > We do need to work out if the docs should capitalize the display name:
>> > "Report Element" or "report element". Once the decision is made, we
>> should
>> > be consistent. For example, when writing a tutorial, should I say,
>> "Next,
>> > create a Label and set its Color", or "Next, create a label and set
>> its
>> > color." (I prefer the latter; it is more natural.) And, either of
>> these are
>> > better, IMHO, to "Next, create a LabelItem and set its textColor" as
>> one
>> > often sees in programming books.
>> >
>> > Also, the names were chosen so that if you were to use a generic phase
>> such
>> > as "report item", or "label" or "color", it would pretty much
>> correspond to
>> > an identical formal name.
>> >
>> > So far everything is simple because we're talking about the
>> design-time
>> > representation. If we have, say, a Label, then we have only one
>> design-time
>> > instance of each label (Label?) we create. (See, there is the case
>> issue
>> > again.) But, at runtime, there is that old one-to-many issue that has
>> > confused so many Actuate e.RD-Pro users over the years: we don't have
>> just
>> > one label, we may have hundreds. We designed one "Customer Name:"
>> label, but
>> > I may have 20 per page in the actual report.
>> >
>> > Hence, the need for two JavaScript objects. We elected to call the
>> > "instance" the same name as the element: "Label". We chose to expose
>> the
>> > design time state as a different object with a different name:
>> "LabelDefn"
>> > (to be changed to "LabelDesign".) Now, we can't really combine the two
>> > without giving up the distinction between design info and instance.
>> Perhaps
>> > we could add a suffix to the state, as you suggest: "LabelInstance" or
>> > "LabelObject"? (I dislike "Object" because there are now different
>> kinds of
>> > object. One would have to understand the difference between a
>> "JavaScript
>> > object" [such as LabelDefn] and a report object such as
>> LabelObject...)
>> >
>> > Since the goal of all of this is to make the system easier to
>> describe, your
>> > feedback on training is very useful. Do you think the possible costs
>> in
>> > confusion of using English names outweigh the benefits of not using
>> > identifiers for everything? For example: "OK, now set the background
>> color
>> > of your text item" vs. "OK, now set the backgroundColor of your
>> TextItem".
>> > Also, the UI would show "TextItem" in the palette vs. "Text Item". And
>> > French, German, Spanish, Chinese and other users would also see
>> "TextItem"
>> > instead of the translated equivalent of the term "text item". Do you
>> think a
>> > non-English speaking student would prefer text with translated words
>> for
>> > "background color" and "text item", or would they prefer text with the
>> > formal English names?
>> >
>> > What do you think?
>> >
>> > - Paul
>> >
>> > Paul Rogers
>> > Actuate Corp.
>> > BIRT PMC
>> >
>> >
|
|
| | |
Goto Forum:
Current Time: Sat Jul 13 18:34:08 GMT 2024
Powered by FUDForum. Page generated in 0.04247 seconds |
] 
Search
Help
Register
Login
Home
