Re: Policy modeling

Hi,

I found a sample Employee Handbook on the Society for Human Resources website that furnished some real-life examples of policy. I have attached a .zip with three small topics using the principle markup. The topic on Confidentiality combines two closely related items into topic. I used <expectationGroup> to keep them separate.

Take a look at it and consider whether the tag vocabulary is appropriate. Can you identify opportunities for additional tag names within this content? Or, do you feel that some tag names are needlessly specific?

One thing became apparent during this exercise: we will need to try any vocabulary we come up with on a wide variety of use cases.

Best Regards,

Bob

On Sun, Mar 1, 2015 at 10:22 PM, Bob Thomas <bob.thomas@tagsmiths.com> wrote:

Coverage concerns

When I spoke with Raymond Urgo in January he asked us to consider where the following sorts of information would go:
importance
revision
review
appeal
Importance

I assume that Raymond had some sort of classification scheme in mind, such as high, medium, and low. We could create an "importance" attribute for <policy>. The classification tokens for importance should probably be left unspecified.

Revision and review

These are both processes that could be marked up with task.

Appeal

This sort of information could be marked up with troubleshooting.

Nature of policy

Observations

Raymond observed that policy information is inherently abstract since it usually deals with expectations rather than objects. Consequently, any model we come up with must be quite flexible. He pointed out being too prescriptive with our model would limit its usefulness. The work that he has done with clients bears this out. He was emphatic that forms or template-based solutions are too rigid.

Implications

In light of Raymond's remarks, I noticed that the section-like elements in the XML that I showed him naturally split into two categories expectations and qualifications on those expectations. This suggests that a wrapper element (e.g., <expectationGroup> might be useful for grouping.

Where to put the <policy> tag?

My current thinking is that <policy> ought to be a section-level element that signifies a policy statement. For example, "An illness lasting more than 5 consecutive work days must be vetted by HR." I've been thinking about this use-case as policy with a small "p." Contrast this with something like a company's hiring policy. This could be a complex collection of policy statements and rationale that would be linked through one or more DITA maps, or perhaps it could be an entire publication. I've been thinking about these use-cases as Policy with a capital "P".

For Policy with a capital "P," tying the <policy> tag to a topic wouldn't suffice in complex cases, although I suppose you could use it as a wrapper topic in a DITA map. However, if you were to use it as a wrapper topic, the semantics would become nebulous. It is far more concrete to tie <policy> to a policy statement like what happens in policy with a small "p."

If we were to tie <policy> to a policy statement, that would also allow us to use a more general name for the containing topic. I've been calling the topic <principle>. Using a topic name like <principle> would also allow us to introduce other expectation-oriented elements at the section-level such as <requirement> or <regulation>.

Best Regards,
--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype
Time zone: Mountain (GMT-7)

Bob Thomas

+1 720 201 8260

Skype: bob.thomas.colorado

Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype

Time zone: Mountain (GMT-7)

dita-techcomm message