Topics

Any Interest in a Hardware Domain for Non-computer Buttons/Controls? #DITAv2-0

keith@...
 

Hello there:

An idea that is being floated for DITA 2.0 is the introduction of a new hardware domain to provide markup for things like the following:
- keyboard combinations like "Ctrl + Alt + Delete"
- a part number element to mark up part numbers
- a way to mark up non-computer controls, covering things like levers, peddles, switches having multiple selections, etc.
In general, the idea is to provide semantic alternatives for the arguably overused uicontrol element in situations that are not necessarily software related (say, for a control lever on a device, an accelerator or gear-shift for a car (which are forms of discrete controls), or a tuner knob on a radio (which is a continuous control)).

I was asked by the DITA TC to ask the members of this forum their thoughts on this idea in general, and whether people would use this markup if it was available.

If this is of interest, please respond! Whether or not we do this is dependant on the responses we get.

Cheers!

~~~~~~~~~~~~~~~~~~~~~~~~
Keith Schengili-Roberts
DITAWriter.com
Chair of OASIS DITA Adoption

Allan Jenoff
 

I would definitely b using keyboard combinations. It is long overdue.

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of keith@...
Sent: Wednesday, March 25, 2020 10:51 AM
To: main@dita-users.groups.io
Subject: [dita-users] Any Interest in a Hardware Domain for Non-computer Buttons/Controls? #DITAv2-0

 

Hello there:

An idea that is being floated for DITA 2.0 is the introduction of a new hardware domain to provide markup for things like the following:
- keyboard combinations like "Ctrl + Alt + Delete"
- a part number element to mark up part numbers
- a way to mark up non-computer controls, covering things like levers, peddles, switches having multiple selections, etc.
In general, the idea is to provide semantic alternatives for the arguably overused uicontrol element in situations that are not necessarily software related (say, for a control lever on a device, an accelerator or gear-shift for a car (which are forms of discrete controls), or a tuner knob on a radio (which is a continuous control)).

I was asked by the DITA TC to ask the members of this forum their thoughts on this idea in general, and whether people would use this markup if it was available.

If this is of interest, please respond! Whether or not we do this is dependant on the responses we get.

Cheers!

~~~~~~~~~~~~~~~~~~~~~~~~
Keith Schengili-Roberts
DITAWriter.com
Chair of OASIS DITA Adoption

CharJTF
 

I'd definitely be in favor of more semantic alternatives.

Char


On Wed, Mar 25, 2020 at 11:25 AM Allan Jenoff <allan.jenoff@...> wrote:

I would definitely b using keyboard combinations. It is long overdue.

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of keith@...
Sent: Wednesday, March 25, 2020 10:51 AM
To: main@dita-users.groups.io
Subject: [dita-users] Any Interest in a Hardware Domain for Non-computer Buttons/Controls? #DITAv2-0

 

Hello there:

An idea that is being floated for DITA 2.0 is the introduction of a new hardware domain to provide markup for things like the following:
- keyboard combinations like "Ctrl + Alt + Delete"
- a part number element to mark up part numbers
- a way to mark up non-computer controls, covering things like levers, peddles, switches having multiple selections, etc.
In general, the idea is to provide semantic alternatives for the arguably overused uicontrol element in situations that are not necessarily software related (say, for a control lever on a device, an accelerator or gear-shift for a car (which are forms of discrete controls), or a tuner knob on a radio (which is a continuous control)).

I was asked by the DITA TC to ask the members of this forum their thoughts on this idea in general, and whether people would use this markup if it was available.

If this is of interest, please respond! Whether or not we do this is dependant on the responses we get.

Cheers!

~~~~~~~~~~~~~~~~~~~~~~~~
Keith Schengili-Roberts
DITAWriter.com
Chair of OASIS DITA Adoption

Thomas Rathkamp
 

I "third" that motion ;)



Tom Rathkamp
Senior Technical Writer




On Wednesday, March 25, 2020, 10:38:35 AM CDT, CharJTF <charjtf@...> wrote:


I'd definitely be in favor of more semantic alternatives.

Char

On Wed, Mar 25, 2020 at 11:25 AM Allan Jenoff <allan.jenoff@...> wrote:

I would definitely b using keyboard combinations. It is long overdue.

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of keith@...
Sent: Wednesday, March 25, 2020 10:51 AM
To: main@dita-users.groups.io
Subject: [dita-users] Any Interest in a Hardware Domain for Non-computer Buttons/Controls? #DITAv2-0

 

Hello there:

An idea that is being floated for DITA 2.0 is the introduction of a new hardware domain to provide markup for things like the following:
- keyboard combinations like "Ctrl + Alt + Delete"
- a part number element to mark up part numbers
- a way to mark up non-computer controls, covering things like levers, peddles, switches having multiple selections, etc.
In general, the idea is to provide semantic alternatives for the arguably overused uicontrol element in situations that are not necessarily software related (say, for a control lever on a device, an accelerator or gear-shift for a car (which are forms of discrete controls), or a tuner knob on a radio (which is a continuous control)).

I was asked by the DITA TC to ask the members of this forum their thoughts on this idea in general, and whether people would use this markup if it was available.

If this is of interest, please respond! Whether or not we do this is dependant on the responses we get.

Cheers!

~~~~~~~~~~~~~~~~~~~~~~~~
Keith Schengili-Roberts
DITAWriter.com
Chair of OASIS DITA Adoption

Reece Roggentien
 

I’d also use keyboard combinations. Similarly, there are hardware components or interactions that aren’t part of a keyboard but perform similar functions. On Windows, for example, I might use “Ctrl+P” to take a screenshot while on my iPhone I’d press “Power + volume”. Gestures are also common and I could see myself using a <gesture> tag or something like it.

 

-Reece

 

:main@dita-users.groups.io] On Behalf Of Allan Jenoff via Groups.Io
Sent: Wednesday, March 25, 2020 10:25 AM
To: main@dita-users.groups.io
Subject: Re: [dita-users] Any Interest in a Hardware Domain for Non-computer Buttons/Controls? #DITAv2-0

 

I would definitely b using keyboard combinations. It is long overdue.

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of keith@...
Sent: Wednesday, March 25, 2020 10:51 AM
To: main@dita-users.groups.io
Subject: [dita-users] Any Interest in a Hardware Domain for Non-computer Buttons/Controls? #DITAv2-0

 

Hello there:

An idea that is being floated for DITA 2.0 is the introduction of a new hardware domain to provide markup for things like the following:
- keyboard combinations like "Ctrl + Alt + Delete"
- a part number element to mark up part numbers
- a way to mark up non-computer controls, covering things like levers, peddles, switches having multiple selections, etc.
In general, the idea is to provide semantic alternatives for the arguably overused uicontrol element in situations that are not necessarily software related (say, for a control lever on a device, an accelerator or gear-shift for a car (which are forms of discrete controls), or a tuner knob on a radio (which is a continuous control)).

I was asked by the DITA TC to ask the members of this forum their thoughts on this idea in general, and whether people would use this markup if it was available.

If this is of interest, please respond! Whether or not we do this is dependant on the responses we get.

Cheers!

~~~~~~~~~~~~~~~~~~~~~~~~
Keith Schengili-Roberts
DITAWriter.com
Chair of OASIS DITA Adoption

Ute Methner
 

Yes, that would be very useful to have.

--



Thank you
Ute


Ute Methner
Sr Analyst Content Development
Technical Publications
Motorola Solutions

o:
+1.819.931.2170






Your privacy is important to us. That is why we have taken appropriate measures to ensure the data you provide to us is kept secure. To learn more about how we process your personal information, how we comply with applicable data protection laws, and care for the security and privacy of your personal data, please review our Privacy Policy. If you have any questions related to data protection and compliance with applicable laws, please contact us at our Security Operations Center at 1-800-674-4357.

 

Absolutely! 
I would use the keyboard and part number items. 
Under UI items, being able to conceptually (and consequently visually) distinguish radio buttons, menus and their items (menu, menu_item), tabs and sub-tabs, and the like would be very useful.  In an XML-defined UI, the definition could be linked between the app and the documentation.

Grant Hogarth 
Technical Writer, Services Tools team
Workiva Inc. 
1700 Platte St, Suite 200, Denver, Colorado 80202 
Mobile: 1-801-815-8353 


On Wed, Mar 25, 2020 at 9:20 AM <keith@...> wrote:
Hello there:

An idea that is being floated for DITA 2.0 is the introduction of a new hardware domain to provide markup for things like the following:
- keyboard combinations like "Ctrl + Alt + Delete"
- a part number element to mark up part numbers
- a way to mark up non-computer controls, covering things like levers, peddles, switches having multiple selections, etc.
In general, the idea is to provide semantic alternatives for the arguably overused uicontrol element in situations that are not necessarily software related (say, for a control lever on a device, an accelerator or gear-shift for a car (which are forms of discrete controls), or a tuner knob on a radio (which is a continuous control)).

I was asked by the DITA TC to ask the members of this forum their thoughts on this idea in general, and whether people would use this markup if it was available.

If this is of interest, please respond! Whether or not we do this is dependant on the responses we get.

Cheers!

~~~~~~~~~~~~~~~~~~~~~~~~
Keith Schengili-Roberts
DITAWriter.com
Chair of OASIS DITA Adoption

Kristen James Eberlein
 

Folks, let me focus the discussion a little more clearly.

The DITA TC is looking to introduce a domain for hardware controls into DITA 2.0. The question is really how extensive it should be. Would a single element (let's call it <hw-control>) suffice, or do we need more? For example, a discrete control (on/off; 1/2/3/4/5 on a gear shift) or a continuous control (volume control for a radio.)

What we need from you is the following information:

  • What are your current unmet needs for documenting hardware controls?
  • How are you currently documenting hardware controls?
  • (If you specialized) What elements did you create, what are the semantics, and what was the business requirements for the specializations?

In other words, please give us more data than "Yes, I'd find it useful." Why would you find a hardware control domain useful? What are your business requirements?

There is good academic data on hardware controls, which Keith Schengili-Roberts looked at and led to the DITA TC knowledge about discrete and continuous controls. However, we want information and requirements from the user community. That's you :)

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of keith@...
Sent: Wednesday, March 25, 2020 10:51 AM
To: main@dita-users.groups.io
Subject: [dita-users] Any Interest in a Hardware Domain for Non-computer Buttons/Controls? #DITAv2-0

 

Hello there:

An idea that is being floated for DITA 2.0 is the introduction of a new hardware domain to provide markup for things like the following:
- keyboard combinations like "Ctrl + Alt + Delete"
- a part number element to mark up part numbers
- a way to mark up non-computer controls, covering things like levers, peddles, switches having multiple selections, etc.
In general, the idea is to provide semantic alternatives for the arguably overused uicontrol element in situations that are not necessarily software related (say, for a control lever on a device, an accelerator or gear-shift for a car (which are forms of discrete controls), or a tuner knob on a radio (which is a continuous control)).

I was asked by the DITA TC to ask the members of this forum their thoughts on this idea in general, and whether people would use this markup if it was available.

If this is of interest, please respond! Whether or not we do this is dependant on the responses we get.

Cheers!

~~~~~~~~~~~~~~~~~~~~~~~~
Keith Schengili-Roberts
DITAWriter.com
Chair of OASIS DITA Adoption

ronny.flink@...
 

Hi,
It would be useful.
Sometimes the UI is not translated. So hardware <uicontrol> are translated  but not software <uicontrol>.

Best regards
Ronny Flink

Larry Kollar
 

Personally, the only hardware controls I have to document are reset and WPS buttons, so maybe I'm not the right person to answer this. I'll check with other teams, they might have needs I don't.

Keystrokes might be a good thing to have an a hardware domain. A long time ago, I built and used a focused XML grammar that included keystroke as an element. Another thing to ask the other teams: to see what they're using. I use userinput, and some others might use uicontrol or plain text. Without a specific element, it's easy to get inconsistent.

For things like Ctrl+P or Alt-Shift-3, there could be a wrapper element analogous to menucascade. Maybe call it keycombo, and use it like this:

<keycombo>
    <keystroke>Ctrl</keystroke><keystroke>Shift</keystroke><keystroke>8</keystroke>
</keycombo>

An alternate and more concise structure:

<keycombo modifiers="Ctrl Shift">8</keycombo>

People who want to get really fancy could use one of those typewriter key typefaces to render them.

Note that we haven't specialized anything here—like I said, we're probably using existing elements inconsistently.

Tom Magliery
 

Here is an example usage that maybe can go into the next version of the spec.

David Yin
 

I am going to put a vote in that YES hardware controls need an element.  I would request a separate element to define a hardware control itself and possibly another mechanism (element or an attribute of an element) that identifies the control’s function/operation.  For the current landscape of our products, more than these two suggestions would be an overkill.

 

In the automotive industry, there are a proliferation of buttons/wheels being designed into the steering wheel.  And the current vocabulary doesn’t allow us to delineate those controls from the software UI controls.

 

David Yin

Technical Publication Manager  |  david.yin@...  |  940.591.4196

DRIVING UPTIME EVERY DAY logo w RED PB EMAIL SIG One Line SMALL 2