Re: [dita-lightweight-dita] Thoughts on a survey

[<jang@jang.nl>]

Thanks for the extra info about the intended audiences. I am hoping this survey will be done in the proper way, i.e. using one of the free online survey tools, rather than sending them in e-mails. Given that assumption, it would be a good idea to have a first question determine whether respondents know anything about DITA or not. If not, we need not ask them about DITA in their organisation and should not refer to the DITA name but instead ask for the tools and formats they are currently using to create product documentation and/or marketing materials.

If I am a casual author and I see questions about some acronym I do not even know, I will quickly decide this survey is not for me. And I am wild guessing that for us the responses of these casual authors would be more interesting than the ones from DITA-savvy authors (who do not need LWDITA themselves but are imagining what others in their organization might want or need).

In fact, the survey should be designed to have clear and separate paths. Asking questions that are irrelevant based on earlier answers is deadly for the enthusiasm of a respondent.

Op 30 juni 2016 03:15:24 +02:00, schreef Michael Priestley <mpriestl@ca.ibm.com>:

Hi Jang,

We need to be clear that we're asking both existing users of DITA (not currently LWDITA), and potential users of DITA (especially LWDITA). We do ask about potential benefits in question 8, although definitely open to identifying/asking for more.

The first question is for existing users, the second for potential users. I think really all of the questions except for the first one are meant to be about current (and presumably mostly non-DITA) practice.

Question 3 shouldn't mention LWDITA at all - I think it was originally about source format, and it's now a mix of source formats and editor tools - we need to go with one or the other. It sort of depends on survey audience - developers might be more comfortable answering the format question (which is one I do care about - especially knowing if we have JSON to deal with), authors will be more comfortable with the tool question.

Agreed on the mistake in block elements - <pre> is preformatted text, not prerequisites. Good catch.

Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com

From:        <jang@jang.nl>

To:        

Cc:        <dita-lightweight-dita@lists.oasis-open.org>

Date:        06/28/2016 02:34 PM

Subject:        Re: [dita-lightweight-dita] Thoughts on a survey

Sent by:        <dita-lightweight-dita@lists.oasis-open.org>

---

The wording of several questions in this survey speaks to current users of LW-DITA, of which there will not be too many, as we are still in a concept phase of defining it. To get input from areas that we hope to be targeting with LW-DITA, this should be changed to address their current practice and ask what advantages they would expect from using LW-DITA. Depending on the target audience for the survey, an introduction about DITA vs LW-DITA might or might not be relevant.

Question 3 seems to lean toward a community that is currently using other lightweight content solutions, but asks which tools are being used to create LW-DITA content. I would expect not a single option to be checked by anyone. The question seems to ask which tools are currently used to create the type of content that could be authored in LW-DITA, but as hardly anyone knows LW-DITA that should be described in a different manner. JSON should be removed from the list of authoring tools in any case, as it is a format, not a tool.

Apart from these general remarks, I believe there is at least one error in the elements listed for question 6. The [pre] element is Preformatted text. If Prerequisite is meant, it should be [prereq], but I don't think that is one of the basic block elements for generic authoring.

My 2 cents.

Op 28 juni 2016 19:34:30 +02:00, schreef :

I reviewed the survey and cleaned it up a bit. Here's what I came up with:

The Lightweight DITA committee wants to understand more about how DITA is, and could be, used inside of organisations to manage their content more efficiently and get more benefit from their content.

 

Using DITA allows users to [fill in here with description of lightweight DITA]

 

1.        Which of the following  roles are creating DITA today in your organization? Choose as many options as apply. If possible, point us to an example by providing a URL for each type of content you now produce using DITA.

 

[will need to have clearly-indicated field for URLs or comments]

• Content designers
  
• Content developers
  
• Content editors
  
• Customer support staff
  
• Embedded assistance authors
  
• Help/UA authors
  
• Marketing communicators
  
• Policy and procedure authors
  
• Product documentation authors
  
• Sales people
  
• Trainers - Non-technical
  
• Trainers - technical
  
• Software Designers
  
• Software Developers
  
• Support staff (Pas)
  
• Subject matter experts - non-technical (eg marketing)
  
• Subject matter experts - technical
  
• Other (specify)
  

 

2.        In which content areas are you considering Lightweight DITA? Choose as many options as apply. If possible, point us to an example by providing a URL for each type of content you would like to produce using DITA.

 

[will need to have clearly-indicated field for URLs or comments]

• Content designers
  
• Content developers
  
• Content editors
  
• Customer support staff
  
• Embedded assistance authors
  
• Help/UA authors
  
• Marketing communicators
  
• Policy and procedure authors
  
• Product documentation authors
  
• Sales people
  
• Trainers - Non-technical
  
• Trainers - technical
  
• Software Designers
  
• Software Developers
  
• Support staff (Pas)
  
• Subject matter experts - non-technical (eg marketing)
  
• Subject matter experts - technical
  
• Other (specify)
  

 

 

3.        What authoring tools do you use to write your content in Lightweight DITA?

• Help Authoring Tool (if so, which one)
  
• HTML editor
  
• JSON
  
• Markdown
  
• Microsoft Word
  
• XML editor
  
• Other (specify)
  

 

4.        What delivery formats are important for your use of LW DITA?

• ePub
  
• HTML
  
• JSON
  
• Microsoft Word
  
• PDF
  
• XML
  
• Other (specify)
  

 

6 - Lightweight DITA has the following "block-level" elements [plain English definition]. Are there are elements that you would consider important to be missing from this list?

• Figure [fig]
  
• Footnote [fn]
  
• List - Definition [dl]
  
• List - Ordered (numbered [ol]
  
• List - Unordered (bulleted) [ul]
  
• Multimedia - Audio [audio]
  
• Multimedia - Video [video]
  
• Note [note]
  
• Paragraph [p]
  
• Prerequisite statement [pre]
  
• Table - Simple [simpletable]
  

 

[Add any missing elements.]

 

7.        Some organisations may want to specialize (customise) Lightweight DITA for their specific content needs. If you plan to specialize, which of the following capabilities are must-haves?

• Being able to have containers within containers? (Nested div structures for deep containment specializations)
  
• The ability to choose which attributes you add to content? (Base attributes for arbitrary attribute definition)
  
• The ability to re-use a central specialization (Multiple-level specialization - the ability to specialize off other specializations, not just topic) 
  

 

8.        Which of the following benefits/features of LW DITA matter to you?

• Simpler XML authoring
  
• HTML5 authoring
  
• Markdown authoring
  
• Easier specialization
  
• Easier tools development
  
• Cross-silo content sharing
  
• Cross-silo tool sharing
  
• Other (specify)
  

 

9.        If we have questions or want more information about your answer, could we contact you to followup? If so, please provide an email address.