[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: More ICOM editing notes
Greetings! I didn't have as much free time as I had hoped over the holidays. :-( But, I did get some suggested edits done, backing down to page 109.Barring natural disaster, etc., I hope to finish out by late this week, early next on this pass.
BTW, thanks to Laura for the wiki pages! Hope everyone is having a great week! Patrick -- Patrick Durusau email@example.com Chair, V1 - US TAG to JTC 1/SC 34 Convener, JTC 1/SC 34/WG 3 (Topic Maps) Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300 Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps) OASIS Technical Advisory Board (TAB) - member Another Word For It (blog): http://tm.durusau.net Homepage: http://www.durusau.net Twitter: patrickDurusau
ICOM Editing Notes - icom-ics-v1.0-csprd02.docx Last line prior to today: 203, 7047-7050, I would delete: "to express that" and leave "a conference session ended after the host left" and similar revisions on the following lines. ***** 203, 7046, "There are four conference session states defined by ICOM" -> ICOM defines four conference session states: (voice) [correction of my correction (see below "conflict with line 6926" -> Should read: "The ConferenceSessionEndingReason class defines four conference session states:" Avoids the conflict with line 6926 (which also needs to be re-written) and probably need a note here about conference sessions, which applications may manage together. Insert After line 7018: "Note: Other conference session states are defined by the ConferenceState class 4.11.3" Is there some reason for two conference state classes? No real preference, just seems cleaner to have all session information together. There are approximately 157 occurrences of "defined by" and 32 instances of "defined by ICOM" I suggest the 32 cases of "defined by ICOM" certainly be changed and the remaining 125 be considered on a case by case basis. (I will not be commenting on these cases individually.) Trying to resolve the next problem made me realize that "...four conference session states..." is incorrect. (now corrected my comments) There has to be a conference state for "ongoing," yes? Ah, *conflict with line 6926* - "There are five conference session states defined by ICOM:" (This is the only session state conflict.) 202, 7040-7041, "An enumeration of the instances each of which expresses a reason for ending a conference session." Err, but icom_conf:Hibernating does not record the end of a conference session - yes? Suggest: "Value: Defines reasons for ending conference." I am not real sure about "hibernating" = ending. 202, 7022, "The ConferenceSessionEndingReason class is defined by the attribute values:" Let's make my comment at 203, 7056, general to all 123 instances of "is defined by" and change to "has the attribute values" 202, 7020-7021 "The ConferenceSessionEndingReason class is an enum class that enumerates the instances each of which expresses a reason for ending a conference session." If it enumerates, doesn't that already mean it is an enum class? Try: "The ConferenceSessionEndingReason class enumerates values which specify the reason for ending a conference session." 202, 7016-7017 "...which are implementation-defined." 73 times. Do we mean to restrict what may define additional properties? That is only implementation-defined or can other profiles/standards define additional values for ICOM classes? Thus: "The ConferenceSession class MAY include additional property definitions." (we would need a note somewhere about this meaning.) 201, 7001 Address of a server that hosts a conference session. -> Address of the server that hosts a conference session. BTW, property type string? 199, 6919, "An enumeration of the instances each of which expresses a session state of a conference." -> Session state of a conference. 198, 6867-6869 "The ConferenceType class is an enum class that enumerates the instances each of which expresses a type of a conference". Again the enum class that enumerates, try: The ConferenceType class enumerates the values that specify a type of conference. To return to 199, 6892-6896 - the conference types, are these valuable/useful? Just curious. Why not just have string? 198, I don't have a line number, the class image. Can we link the boxes to the class definitions in the document? Just curious. 197, 6843, 6852 - How would I distinguish between a current or future start/end time? 196, "The Conference class inherits property definitions from super classes." - Err, doesn't that seem a big vague? Which super classes? 72 instances, I won't comment on them separately. Not sure it is necessary b/c at the super classes we can say: x, y, z subclasses inherit from B superclass. Yes? Easier than re-writing that line. 195, 6769, "A conference is a *folder that represents a durable context* for conference sessions." In what sense a "folder?" And what is "durable context?" Do we define that? I think what is meant is: The Conference class is an extension of icom_core:Folder and defines the attributes and values associated with a conference. (or something like that) I would drop: 195, 6770 "It contains conference metadata, settings, and transcripts." Not specific enough to be helpful. Lots of other things could be said there. 195, 6756 "enumeration of the instances" 24x instances. try -> Defines values reflecting the status of an announcement. (and correct all the others as well) 195, 6746 - This happens elsewhere but why do we have extendsFrom with a blank Value: ? Is that informative? 193 6700-6701 "An announcement is a special topic for discussions that are valid for a specified period of time." The way this reads, the "discussions" are valid for "a specified period of time." Not sure that is correct. An announcement might have no expiration. - All staff much change ICOM logins every 6 months, with 16 character passwords and 24 character user names. ;-) Besides, isn't the "description" here of the class? Not its possible content? Try: Defines values for read only messages with activation and possible expiration times. 193, 6682-6683 - try: An announcement is a read only message that may have an expiration time. (Don't you think activiation is implied by the message being sent? Or is that separate?) 192, 6646 "A topic is a folder that contains discussion threads." But under 126.96.36.199 Class Definition (192, 6630) we are talking about "topic" as a class. I may be seriously mistaken but the text seems to be mixing classes and implementation details, such as folders. 192, 6628-6629 - same issue, now calling "topic" a folder. Part of the problem is name overloading between classes and implementation details, such as folders. BTW, limiting sorting to chronological order or threaded by reply is ok but why not add subject? 191, 6584 - folder? is forum a class or a folder? If class -> The folder class defines values for sub-forums, topics and announcements. (Note, no "," before the and.) 190, 6567 - folder? 189, 6543-6544 "TopicContainer is a mixin class *which* defines the characteristics of entities that contain Topics." -> TopicContainer is a mixin class *that* defines the characteristics of entities that contain Topics. 188, 6527 - same as 189, 6543 187, 6464 - same as 189, 6543 What the hell, generalize "is a mixin class which defines the" to "is a mixin class that defines the" for all 24 instances. 186, 6447 "...defines the characteristics of entities that contain..." What happened to folders? I don't like "folders" but let's be consistent. 186, 6445 "A discussion container is a container of discussions." ?? Can't define something in terms of itself, even using the plural form. ;-) Try: "The DiscussionContainer class defines properties of containers for discussion items." Yes? 186, 6423-6324 "Discussion is a mixin class which defines the characteristics of entities that can be placed in a DiscussionContainer." But if DiscussionContainer is a class, no entities can be placed in it. Perhaps: "...that can be placed in containers defined by the DiscussionContainer class." ??? 185, 6406-6407 - same issue as 186, 6423-6424 (except what are elements?) 14x on elements, 48x on entities - need to check for consistency 185, 6395-6396, 6397-6399, "etc." has no place in normative language. Either we define what is meant, or we don't. Can't leave people to guess. happens 8x - let's clear all of them. Either re-write to insert complete references or remove the listing as incomplete. 184, 6358 - "There are eight task participant¡¯s status defined by ICOM:" in addition to the usual re-write, "the relationship of a partcipant to a task has eight possible statuses" Or something like that - may need to discuss. 184, 6365 - "...as assignee is tenative about a task status." Do we mean tenative about a task? Being tenative about "task status" sounds like the excuses that managers get all the time. ;-) 178, 6140 artifact? artifact, 139x - so far, folders, entties, artifacts (Ah! You are using the icom_core classes to say "artifact" etc. Not all that transparent. In some sense they are all class extensions as well, but you would not say: An occurrence is a class extension that represents an event in a calendar. (the place where I realized where you were getting artifact, etc.)) 177, 6094 "folder" is back 174, 6002, free busy interval or FreeBusyInterval? 174, 6004-6005, passive voice, suggest: "If a free busy type is icom_cal:Busy, then a time interval is not free for scheduling." 174, 5993 "A list of participants whose free busy intervals are merged." -> "A list of participants." They are *not* participants b/c their free busy intervals have been merged. In fact, this is the only use of "merged" so that means we failed to define this elsewhere. Yes? I suspect that should have been under 172, 5932 FreeBusy Module. Yes? 168, 5749 and 5751 to explress cancellation/confirmation of an occurrence or occurrence series. (voice) 166, 5695 "Participant transparency..." I searched our document without finding a definition. Does this means transparency in the sense of RFC 2445? Seems like we should be a bit clearer about that point. 164, 5614 icom_cal:exceptionToOccurrenceSeries - I understand this means an exception to some occurrence series but what does that mean? What are its semantics? Does it mean it has different properties than other occurrences in the series? If so, which ones? All? Then how is an exception any different from simply having a unique occurrence declared outside of any occurrence series? 164, 5599 "An occurrence series that includes an occurrence." ?? Do we mean "...that includes multiple occurrences." ?? But why else have a series? Or do you want to have 1...n for any series? 164, 5602 btw, it would be helpful if the Property Type: values were hyperlinks. Mostly because I can't search for icom_cal:OccurrenceSeries as a string. Why? b/c we define the class icom_cal and then define the class under it, OccurrenceSeries, which differs from icom_cal:occurrenceSeries only in capitalization of the "o" in occurrence. Clever but not terribly helpful. Remember, we don't want people to memorize the document to use it. 160, 5478 - "An attendee of an occurrence series." Can attend an occurrence but not sure about being an attendee of a series. Isn't attendance per occurrence? 160, 5470-5471 "One or more simple content attachments in an occurrence series." Delete "simple" unless that has some significance. 159, 5430 Participants *of* an occurrence series. of -> in ? 157, 5354 "is an artifact" extension of icom_core:Artifact - After thinking about it some more, suggest just say series is a class instance for all these cases because the type of object (in the implementation sense) is really up to the implementation. It is no more an artifact that earlier things were folders. They are extensions of those classes. Not the same thing. 157, 5342 "Recurrence elements of a calendar" Do we mean elements -> entries? Or does elements have a broader meaning? 156, 5326 "Time zone of a calendar." Calendars don't "have" time zones. I prefer "Time zone setting for a calendar. That is a time zone is separate from a calendar. 156, 5316-5317 (here we start to trip up with the folder/artifact, etc) "A calendar is a folder that contains time management artifacts such as occurrences and occurrence series." Is that all it can contain? Or we giving an example in normative language? Let's take out "such as" and reform the language on folder/artifacts. BTW, there are 23 "such as" cases. Let's resolve all of them. 153, 5195 "simple content attachments" -> "content attachments" (unless "simple" in this context has special meaning) 152, 5187 "Time zone of a person." ?? Ah, "A person's time zone." Yes? 152, 5179 "A person which is bookmarked by a contact." Questions: Is this a property that indicates a person's record has been bookmarked? if so, try: "PersonContact class instance has a bookmark." I am guessing on this one. There are semantics of some implementation that aren't clear. Such as how does a contact bookmark a person? Or is there some other mechanism? Or none at all? 151, 5130 "Sub-address books in an address book." OK, so where is the address book? addressBook -> sub-addressBooks. All I see is the latter. 151, 5122 btw, 5130 conflicts with 5122 - An address book is a folder that *contains addressable contacts.* NOT sub-address books in an address book. Yes? 150, 5089 - just a reminder about "defined by..." 148, 5012 "what a presentity is" ? I have no idea. but mis-spelled. perhaps "An activity object describes an activity." ??? 147, 4995 - same as 148, 5012 145, 4974-4975 - "a reachability status of a contact method." At page 97, we define: PersonContact to include: "It can also contain addresses, phone numbers, and other entries about an external person." So, how is any system going to display reachability information for an address? Jumping ahead a bit but remind me to ask about Presence - why doesn't it use contact information from elsewhere? and actitives from calendar? 145, 4946 - "A note about a contact method in a presence." ?? That sounds like a note about an address or other contact. 145, 4938 - See 145, 4974-4975 same issue 144, 4921 presentity - ok, I got curious, 35 times. Let's kill them all. 143, 4888 "describes reachability *circumstances* of a..." And what are those? 143, 4864-4865 - see comments about contact information - isn't this duplication? 139, 4766 "It includes a list of the activities describing what a presentity is doing." Assuming better spelling: "It is includes a list of activities for XXX." It cannot be describing what XXX is presently doing, it can only list what XXX is supposed to be doing. Not the same thing. 139, 4743 Note to be propagated to an -> Note propagated by an associated... 139, 4735 Priority to be propagated to an -> Priority propagated by an associated... (now if I just knew what a priority was) 138, 4726-4727 "Reachability status to be propagated to an associated contact method." -> Reachability status propagated by an associated contact method. 138, 4692-4693 "An instant message connection contains the queues for inbound and outbound instant messages." -> An instant message connection contains queues for inbound and outbound instant messages. 137, 4673 "An instant message connection contains the queues for inbound and outbound instant messages." -> An instant message connection contains queues for inbound and outbound instant messages. 136, 4661 "A queue for outbound instant messages." Needs a reference to the inbound queue See page 139, line 4750 135, 4612 "...enumeration of the instances...? see earlier comments on value listings 134, 4578-4589 - drop "to express that an" and just "Instant message is..." 132, 4523 "A formatting style of rich text message in xhtml." -> Text message in xhmtl. 131, 4498 -> A list of participants to receive a message. 131, 4488-4489 "..is a special type of message for one-on-one,..." but at line 4498, we have a list of participants. Not really one-on-one. 129, 4458-4460 - to express - reform 128, 4425-4428 - to express - reform 128, 4419 - enumeration - reform 128, 4389-4396 - to express - reform 127, 4382 - enumeration - reform 127, 4350-4358 - to express - reform 126, 4342 - enumeration - reform 124, 4244-4248 - "..and other custom headers."? What am I required to handle? What is a "printable header string?" What are ascii and non-ascii strings? This seems underdefined. 124, 4235 - how is "delivered" and editable mode? Just curious. 123, 4209 - is requested -> requested 123, 4184-4185 -> as defined in RFC 2183 specifies a presentation style 122, 4174-4176 additional...including....etc. - Sorry, either we state the normative requirements or we leave them alone. 122, 4157 -> A list of participants to receive reply messages. 122, 4148 -> to receive blind-carbon-copies of a message. 122, 4139 -> to receive carbon-copies of a message. 121, 4231 -> to receive a message. 121, 4122 envelop -> envelope delete (sometimes called return path) add: Note: Evelope sender is aslo known as return path. 121, 4112 "special type of message..." special how? 121, 4092-4095 is a type of -> is a... 121, 4092 that is delivered -> delivered 120, 4089 - special? how? 120, 4070 -> When a recipient receives a message. (time is only part of when, date counts as well) 119, 4031-4033 why do we have this note? What does name "holds the subject of a message" mean? For a phone call for example. 117, 3980 a "rendered page and a rendered content." ?? I don't know what either of these mean or even why we have this. Pages or objects can't be rendered until displayed and if we are talking about stored, they aren't rendered. 115, 3948-3949: -> that may contain contents composed of one or more media types. Note the use of "may" does not require more than one, but at least one. Yes? 115, 3919-3926 to express - reform 112, 3820-3822 This seems confused to me. "A version is a version control metadata that contains a version number, label, and description." "A version" here refers to something subject to versioning, for which we have version metadata. Perhaps -> A version is a object for which versioning metadata containing version number, label and description is recorded (captured, whatever). A version object is a version control metadata of a versioned copy or a private working copy of a versionable artifact. Perhaps -> A verion object contains the version control metadata for a versioned object. ??? 112, 3800 "A checked out comment of a version series." I think we meant: A comment on checkout of a version series. Yes? 110, 3734-373 is a version control -> is version control 109, 3693-3694 - characteristics of entities? ...for version control? 109, 3676-3676 - entities? Don't know where that comes from, unlike folder, artifact, etc. 109, 188.8.131.52 Description - usually description, only now lapses into MUST language. Need to separate into a subsection at least.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]