Skip to main content

Home/ DITA XML/ Group items tagged help

Rss Feed Group items tagged

Filter: All | Bookmarks | Topics Simple Middle
Jason Owen

Encoding context-sensitive help information in DITA reltables | Scriptorium Publishing - 0 views

www.scriptorium.com/...-information-in-dita-reltables

dita contentmanagement contexthelp help relationshiptables

shared by Jason Owen on 29 Jun 12 - No Cached
  • If a help ID should provide a list of related topics, those topics are shown as separate <relcell> entries in the corresponding <relrow>:
  • <relrow id=”h4444444″>
  • This encoding approach takes care of the DITA source side of the context-sensitive help. You’ll need to build a DITA Open Toolkit plugin that processes the relationship table and creates the appropriate mapping files.
Jason Owen

Metadata Principle 2 | framework.niso.org - 0 views

framework.niso.org/25

shared by Jason Owen on 21 Apr 10 - Cached
  • Good metadata should be coherent, meaningful, and useful in global contexts beyond those in which it was created.
  • The creation of accessible, meaningful shared collections implies responsibilities on both the part of the data providers
  • The goal of interoperability is to help users find and access information objects that are distributed across domains and institutions.
  • ...1 more annotation...
  • When different metadata schemes must be used, one way to achieve interoperability is to map elements from one scheme to those of another. These mappings, or crosswalks, help users of one scheme to understand another, can be used in automatic translation of searches, and allow records created according to one scheme to be converted to another.
Jason Owen

Subject classification with DITA and SKOS - 4 views

www.ibm.com/...x-dita10

DITA skos xml technicalwriting documentation standards

shared by Jason Owen on 21 May 10 - No Cached
  • In a topic-oriented architecture such as DITA, content is authored in small, independent units that are assembled to provide help systems, books, courses, and other deliverables. Each unit of information answers a single question for a specific purpose. That is, each topic has specific, independent subject matter
  • Because each topic has a specific meaning, DITA topics are tailor-made for semantic processing. However, current semantic processors can't read the text of a topic to find out what it means. What's missing is a formal declaration of the topic's subject matter that a semantic processor can understand
  • Simple Knowledge Organization System (SKOS) provides a standard for indicating the subject matter of content. SKOS lets you define the subjects for a particular subject matter area (organizing these subjects as a taxonomy if desired) and then classify each piece of content to indicate its subject. For instance, using SKOS, you could define configuration and security as subjects, and classify the three example topics that relate to those subjects so that users could browse the subjects to find the content regardless of whether the words "configuration" or "security" actually appear in the text.
  • ...16 more annotations...
  • SKOS is expressed with Resource Description Framework (RDF), the fundamental language of the Semantic Web.
  • DITA has a natural fit with SKOS in solutions where DITA topics are classified with subjects that are expressed in SKOS for runtime processing.
  • Formal subjects are often defined by glossary topics or other topics that already exist within the published information set.
  • Even if you don't include the subject definitions in your published information, you can use your standard content tools for your subject definitions. For instance, you can author the subject definitions with your XML editor, and archive and version the subject definitions along with your content in your content management or version control system.
  • Subject classification is as much a part of the information architecture of your content as the navigational organization.
  • The DITA topic specifies the subject with a specialized section element that includes the following kinds of information:Default labels, including synonyms and denotative imagesNotes on the definition and on the scope of coverage for the subjectListing 1 shows an example of the definition for the Configuring subject:
  • Because the meaning of a formal topic should never vary based on its use, these fields should be part of the topic.
  • You can have multiple schemes for the same subjects. For instance, different audiences might be interested in a different subset of the taxonomy.This approach of imposing alternative organizational structures on subjects fits well with the standard use of DITA maps for separating context from content, allowing different organizations to be imposed on the same content. That is, the scheme can be considered a special kind of context for subject definition topics.
  • Schemes can use non-DITA subject definitions (such as publicly-defined SKOS, OWL, or TopicMaps subjects). You cite the public identifier of the subject with the subjectdef element and identify the subject definition format with the format attribute. This allows you to incorporate publicly-defined subjects into your schemes, or to integrate a formal ontology maintained by your organization with concepts that are specific to your content.
  • To classify content, another map specialization associates formal subjects with topics (see Figure 4).
  • Inside the topicref element that references and contains references to the classified content, you nest a topicsubject element to specify the subjects of the content. You can identify a primary subject with the href attribute of the topicsubject element, which also contains subjectref elements for the secondary subjects. If no subject is primary, the topicsubject element should be a container without the href attribute.
  • In the same way that subject schemes can cite public non-DITA subjects, you can classify DITA content with SKOS, OWL, or TopicMaps subjects by citing the public URI identifiers with the subjectref element and setting the format attribute.
  • The central circle represents a conceptual topic (such as Security), which:Has a broader relationship to a subject (perhaps System Concerns) within a schemeIs classified by two other subjects (perhaps the Background type and the Novice User role)Contributes to the classification of one topic (such as Web Security)Occupies the second position in a navigation sequence (perhaps under a Glossary heading)
  • Because subjects are defined by special topics, you can include the subject definition in the content and use it for classification. For instance, the subject topic for Security can both classify content about security and describe security within the Web site or help system content. Figure 5 illustrates this scenario:
  • Because the classification map is distinct from the scheme map, you can apply multiple schemes to the same classification without requiring changes to the classification. To combine the scheme and classification maps for a deliverable, a higher-level map can refer to both maps using a DITA map reference (see Figure 6).
  • You might process a single map to generate both an HTML representation of the content and a SKOS representation of the subjects and classification.
  • Jason Owen on 21 May 10
     
    Use a DITA specialization to manage the subject matter of your document content -- that is, identify and process your content based on what each topic is about. With the approach outlined in this article, you can take advantage of the technologies of the
Jason Owen

Do we need a content strategy? | DITA XML.org - 0 views

dita.xml.org/...do-we-need-a-content-strategy

contentmanagement dita contentstrategy

shared by Jason Owen on 05 Jul 12 - No Cached
  • What is a content strategy? A content strategy reveals who the end users are, the goals they are pursuing and what tasks they must do to reach the goals. The content strategy explicitly describes what type of information end users need to do the tasks, which gives us the content to include and not include in a manual and how to organize it to make content searchable. A content strategy shall answer a number of questions (for example, open the document via link "information design questions" On http://www.sesam-info.net/planning.htm). The answers are sometimes referred to as the information model.
  • The content strategy shall also deal with areas such as metadata, reuse strategy, creation and release processes, publishing mechanisms, content ownership and responsibility, tools etc.
  • Let us elaborate two types of content creation organizations within the technical communication domain: Explicit and implicit organizations.  In the implicit organization there are no content strategy written down. Each member (technical writer, SME etc) has their own view on what content they believe end users need. In the best of worlds these views are aligned without the members having discussed it. In other implicit organizations an information designer has taken the role to plan and design the content (together with the team or not). But the strategy and principle that the information designer is following may not be communicated or understood by the technical writers or SMEs. So the information designer has to be consulted every time a new manual is developed or a macro content change is proposed in an existing manual. In explicit organizations the strategy and principles are written down and communicated.
  • ...1 more annotation...
  • What benefits is possible to see from having a content strategy? Content creation teams are spending less time or planning and developing the content specifications, which helps team be more efficient which allows the company to launch the new products faster on more markets. The writing process is likely to improve since it is clear who the end user is and what type of information is needed. The content strategy also reveals the requirements and expectations a company imposes on the content creation team.
Jason Owen

Technical Communication - 0 views

techcomm.stc.org/...n-organizational-communication

knowledgemanagement technicalwriting technicalcommunication wikis

shared by Jason Owen on 21 Apr 10 - Cached
  • in its original conceptualization wiki technology was not developed for the purpose of a public Internet-based encyclopedia but as an internal communication and collaboration platform
  • Wikis are best explained within the larger context of social software. Social software is broadly defined as “software that supports group interaction”
  • The key attributes of wikis and other social software tools are the following (Parameswaran & Whinston, 2007): content is created and controlled by the users; content is highly dynamic with frequent, often unpredictable changes; quality assurance of the content is largely peer-based and unstructured; social software applications themselves are mostly lightweight, platform independent, and highly portable.
  • ...52 more annotations...
  • While in other applications such as forums, blogs, or social networking sites the content generation process resembles a mosaic of separate individual contributions, the wiki-based content creation process describes a confluence of individual contributions.
  • content that has been posted earlier and thereby modify, extend, or adjust its meaning. The refactoring capability of wikis allows for new communication practices. Instead of passively reading content that has previously been posted on the wiki, users actively edit content
  • wiki-based content creation is comparable to the process of collaborative writing, with distributed individuals integrating their expertise into one jointly created document
  • in a wiki-based environment, no coordinator distributes tasks or consolidates the distributed efforts. The users themselves decide how they can best contribute to the content creation process.
  • The widely popular Mediawiki platform (e.g., used by Wikipedia), for instance, contains both content pages and “talk pages.” If the content pages themselves are used mainly for collaborative content creation, then the talk pages enable an ongoing discussion about the collaborative effort
  • writing “above the line” for collaboration and “below the line” for communication in other wikis
  • Although wiki-based communication and collaboration practices have demonstrable advantages (Wagner & Bolloju, 2005), they also create a number of challenges. The process of collaborative content creation is predicated upon the fact that users integrate their diverse perspectives such that the overall content converges toward common agreement
  • The effective use of wiki technology thus requires some kind of governance processes, mechanisms, and mindsets that ensure that user interactions remain constructive.
  • For open, Internet-based wiki platforms, escalation procedures, such as dispute resolution processes, take effect when users cannot constructively integrate their perspectives or act in destructive ways (Viégas, Wattenberg, Kriss, & Ham 2007)). In the context of enterprise wikis, formal roles will be allocated that oversee and facilitate the content creation process. The other core issue of wiki-based collaboration is that the content remains in a “state of flux.” Unless somebody actively “freezes” the wiki content, users can continue to add to it, integrate new perspectives, or change the entire essence of the content. While this permanent “state of flux” allows users to constantly update the content, it limits the ability of the wiki to serve as an “authoritative source,”
  • An area where wikis are commonly used is in requirements engineering, where diverse stakeholders with different backgrounds collaboratively identify and clarify the specifications of software applications.
  • Brown, and Boehm (2008) describe how wikis can assist, not only in the formulation and documentation of user requirements, but also in the negotiation between users and systems developers.
  • The essential message of media choice theories is that based on their characteristics, different media have different communicative capabilities that, based on their fit with the communication task, result in more or less effective communication. Within media choice theories, communication media are understood as systems or software applications that enable or support communication activities.
  • Stein (2008) explicitly refer to wikis as a communication medium. Hence, for the purpose of the present research, we consider wikis as a medium and focus on media richness theory (Daft & Lengel, 1986), theory of media synchronicity (Dennis & Valacich, 1999), and common ground theory (Clark & Brennan, 1991), since these theories have established a diverse catalogue of media capabilities that allow us to systematically characterize wiki technology and to compare it with other communication media.
  • MRT focuses on two core premises (Dennis & Kinney, 1998): (1) communication media differ in richness (the ability to change the understanding of information) and (2) performance improves when managers match the richness of the media with the communication task.
  • MRT argues that some media, which the theory identifies as rich, create a higher social presence that, in turn, facilitates understanding between the individuals involved in the information processing task.
  • MRT categorizes communication media with respect to their inherent richness (Daft & Lengel, 1986). Four media capabilities are used to determine the richness of communication media: multiplicity of cues, immediacy of feedback, language variety, and personal focus (see Table 1).
  • Multiplicity of cues describes the number of ways that information can be communicated through the medium (e.g., text, voice, physical gestures). Immediacy of feedback describes the extent to which a medium facilitates rapid responses. Language variety refers to the ability of the medium to convey natural language (instead of only numeric information). Personal focus describes whether a medium supports the personalization of messages
  • Face-to-face High High High Hig
  • The theory of media synchronicity (TMS) provides a different perspective on media choice by focusing on the ability of media to synchronize communication and collaboration processes in groups (Dennis & Valacich, 1999). It extends MRT by arguing that “[the ability of a medium] to change understanding within a time interval is linked not only to its social factors but also to its information processing capabilities” (p. 2). While MRT focuses on the fit between media capabilities and characteristics of the information processing task, TMS focuses on the fit between media capabilities and the underlying communication processes required. These communication processes are characterized as conveyance (an exchange of information), or convergence (the development of shared meaning).
  • TMS categorizes communication media with regard to three information processing capabilities (parallelism, rehearsability, reprocessability) and two social capabilities (immediacy of feedback and symbol variety) (Dennis & Valacich, 1999). Parallelism describes the number of simultaneous communication processes that can coexist effectively; rehearsability refers to the ability to fine-tune messages before sending; reprocessability focuses on the ability to reexamine information after the communication event; immediacy of feedback follows its MRT-based equivalent; and symbol variety subsumes the multiplicity of cues and language variety of MRT
  • Face-to-face High High Low Low Low
  • Common ground theory (CGT) (Clark & Brennan, 1991
  • Common ground is established through shared experiences and shared knowledge and also as an interactive process during the communication event. In this respect, grounding can be compared to convergence—the development of shared meaning. While MRT and TMS focus on the fit between media capabilities and information processing tasks or communication processes, CGT focuses on the common ground as enabler of communication, which in turn determines the communication media that can be effectively employed.
  • Individuals who are initially lacking common ground require a highly interactive medium that allows for the expression and joint negotiation of common ground. To determine the interactive capabilities, communication media are characterized with regard to their simultaneity, sequentiality, reviewability, co-presence, visibility, audibility, contemporality, and revisability.
  • Simultaneity describes the ability to send and receive information at the same time, while sequentiality specifies that turns cannot get out of sequence. The other capabilities are equivalent to the ones described in MRT or TMS. Reviewability refers to the ability to reexamine information after the communication event (cf. reprocessability in TMS); revisability refers to the fine-tuning of information before the communication event (cf. rehearsability in TMS). Co-presence, visibility, and audibility describe aspects of media richness: co-presence refers to face-to-face interactions, while contemporality is comparable to immediacy of feedback.
  • we embarked on a research project that systematically identified the media capabilities of wikis and analyzed their role in established media choice theories
  • in comparison to chat-based or face-to-face interactions, wikis do not provide a high immediacy of feedback.
  • Wikis are largely text based but are increasingly integrated with pictures and videos to provide additional communication cues. Still, the multiplicity of cues for information exchange is limited when compared to other tools such as videoconferencing.
  • Wikis allow users to input natural language as well as tables and numbers.
  • Wikis are largely a many-to-many communication medium; messages are directed to groups and not to individuals.
  • Wiki users can collaborate on the same document simultaneously. Wikis provide probably one of the highest levels of parallelism among all communication tools.
  • Every editing and posting can be reviewed on the screen before it is submitted to the wiki.
  • Wiki-based content remains a reference point after the initial communication event. Even deleted or modified messages can be reverted to identify previous content.
  • Wiki users are largely dispersed.
  • Wiki users who are editing content are simultaneously reviewing changes and other postings.
  • The summary in Table 4 identifies wikis as a capable technology for communication and collaboration in organizations where careful (rehearsed and revised) discourse is desirable, and where communication results are repurposed.
  • Comparing the media capabilities of enterprise wikis with other communication media, a surprising similarity to email technology emerges.
  • in addition to these similarities, wikis offer a distinct set of advantages for internal communication needs. Email is a client-based technology that distributes multiple, independent copies of identical messages to all receivers, congesting email servers and leading to versioning problems. A wiki, on the other hand, is a server-based technology that allows users to view the same single document, relieving the communication infrastructure of duplicated messages, and counteracting the circulation of multiple versions.
  • This underlying structural difference seems to make the wiki the better choice for a large number of internal communication events in organizations.
  • When interpreted through the lens of media choice theory, the only significant difference between the media capabilities of these two technologies is the ability of email to personalize messages. Based on this ability it can be assumed that emails will remain the media of choice for communication tasks that require personalization.
  • content refactoring clearly constitutes an important capability that is unique to wikis: users continuously modify content after the initial communication event. This capability is significant, as it turns a discrete text-based communication event into an ongoing communication process that (ideally) incrementally increases the information quality.
  • The same capabilities make wikis equally suitable for supporting the idea generation process: setting up a wiki for hashing out ideas allows users to integrate and build upon each other’s ideas
  • The refactoring capability, for instance, enables communication processes usually associated with communication media with a high social presence, such as the processes of negotiation and consolidation (Sullivan, 1995). A good example of this is the identification of user requirements for the development of new software systems (Decker et al., 2007). In this context the wiki is used as a documentation and negotiation platform that complements the face-to-face communication among business analysts and system users.
  • The distributed nature of the wiki allows users to contribute without being inhibited by the physical presence of other contributors.
  • Wikis are very suitable for quickly publishing information to a wider audience, such as providing project updates to stakeholders.
  • Using a wiki in the organizational context requires decisions whether to adopt the open principle and allow every staff to overwrite the existing content, or to impose restrictions and allocate formal roles.
  • users in an organizational wiki will be logged in, and any kind of editing activity will be associated with a particular author.
  • information in the wiki has to be dependable in order to be acted upon. For these kinds of communication activities, some form of approval process is necessary that shows team members that the information in the wiki has been viewed and authorized for further use.
  • The significant success of Wikipedia and other public platforms is the result of the interest and enthusiasm among users in sharing and creating knowledge artifacts.
  • it is advisable to focus on the use of wikis in small teams where members have established a high level of trust. These environments will help users to gain experience in a relatively sheltered context where mistakes or problems are easily rectified or solved. Once users have gained more experience and can see the benefits of wiki-based communication, they may be more prepared to use wikis in larger or more anonymous teams.
  • wiki champions (Mader, 2008). That is, individual staff across the organization have the role of sharing not only the enthusiasm but also the expertise of wikis. Wiki champions explain the wiki concepts to their colleagues and assist them in the wiki use.
  • wikis are particularly well suited for tasks high on language variety, parallelism, reprocessability, and rehearsability
Jason Owen

Why DITA, especially "for the Web?" | DITA per Day - 1 views

contelligencegroup.com/...hy-dita-especially-for-the-web

dita dynamic adaptive contentmanagement publishing

shared by Jason Owen on 07 Mar 14 - No Cached
  • Content that is personalized, easily found, appropriately scoped, and pleasant to interact with has a name: Adaptive Content
  • content should adapt to the reader as well as to the device.
  • Among its high points for alignment with direct-to-Web content delivery solutions, DITA provides: Close affinity to Web page writing conventions and length Intentional similarity of inner content markup names (p, ul, ol, dl, etc.) A close match in its title, short description, and body structure to the way most Web CMS tools manage their content. Maps that work so very well for representing collections of content.
  • ...1 more annotation...
  • On the minus side, HTML content models have evolved well past the internal models that DITA assimilated in 1999, which causes these limitations: Web authors often organize content in patterns that DITA’s content model won’t allow. You can’t always author in DITA “as if it were HTML.” HTML5 has added elements for which there are no equivalent base forms in DITA. Normally, domain specialization in DITA can help rectify this mismatch, but because HTML5 is a “Living Standard” and can add or drop elements as it evolves, an ongoing tension remains between the two formats. Entering values for DITA’s various metadata structures is perhaps harder than it should be for light editing environments.
1 - 10 of 10
Showing 20▼ items per page