The document discusses best practices for using DITA (Darwin Information Typing Architecture). It recommends starting with an audience and task analysis to understand information needs before writing topics. Topics should be written for re-use across products and embrace minimalism by expressing a single idea. The document also stresses the importance of quality control reviews and managing reusable content chunks.
One of an Information Architect’s main roles is to develop and maintain an organization’s Information Model. But it’s usually up to other roles—tools and editorial, specifically—to express and enforce the Model. Wouldn’t it be nice if during the act of writing the Information Model, the IA was simultaneously creating the automatic enforcement and expression of the Model in the authoring environment?
In this presentation, George and Dawn show how an IA can author an organization’s Information Model using DITA topics and maps—as is the industry standard practice—but take it one step further, with the IA’s input being used as the specifications for auto-generated Schematron rules and tool tips.
Discuss the layers of topic-based authoring, best practices for writing at the topic level, single sourcing publishing opportunities and strategic planning to meet challenges along the way.
This presentation is an introduction to the field of technical writing based on my personal journey and philosophy of documentation, and was presented to the first meeting of Write The Docs Nigeria on February 20, 2021.
Technical Delivery - Expanded Role for Technical Communicators, STC New Engla...Todd DeLuca, MTSC
Presentation presented to STC New England chapter in Lowell, Massachusetts (MA) on April 2, 2016. Talks about giving the message of tech comm work directly and not relying on others, including how and what to report (share what you're doing).
One of an Information Architect’s main roles is to develop and maintain an organization’s Information Model. But it’s usually up to other roles—tools and editorial, specifically—to express and enforce the Model. Wouldn’t it be nice if during the act of writing the Information Model, the IA was simultaneously creating the automatic enforcement and expression of the Model in the authoring environment?
In this presentation, George and Dawn show how an IA can author an organization’s Information Model using DITA topics and maps—as is the industry standard practice—but take it one step further, with the IA’s input being used as the specifications for auto-generated Schematron rules and tool tips.
Discuss the layers of topic-based authoring, best practices for writing at the topic level, single sourcing publishing opportunities and strategic planning to meet challenges along the way.
This presentation is an introduction to the field of technical writing based on my personal journey and philosophy of documentation, and was presented to the first meeting of Write The Docs Nigeria on February 20, 2021.
Technical Delivery - Expanded Role for Technical Communicators, STC New Engla...Todd DeLuca, MTSC
Presentation presented to STC New England chapter in Lowell, Massachusetts (MA) on April 2, 2016. Talks about giving the message of tech comm work directly and not relying on others, including how and what to report (share what you're doing).
That is what we presented at the last Minibar here in London on April 25th. It took place at Corbet Place Bar at the entrance of the Trueman Brewery on Friday. Thanks to Christian for organising this great event.
Painless XML Authoring?: How DITA Simplifies XMLScott Abel
Presented at DocTrain East 2007 by Bob Doyle, DITA Users -- This introduction to XML Authoring will acquaint you with over fifty tools aimed at structuring content with DITA. They are not just DITA-compliant authoring tools (editors) for writers. They also include content management systems (CMS), translation management systems (TMS), and dynamic publishing engines that fully support DITA. You will also need to know about tools that convert legacy documents to DITA and help to design stylesheets for DITA deliverables. The best DITA tools for technical communicators implement the DITA standard while hiding all the complexity of the underlying XML (eXtensible Markup Language).
As a tech writer and not a tech, you should be able to forget about XML - except to know that you are using it (DITA is XML) and that it consists of named content elements (or components) with attributes. You need to know enough about the content elements so you can reference (conref) them for reuse. You need to know about their attributes so you can filter on them for conditional processing. And you should appreciate that because components are uniquely identifiable they lend themselves perfectly to automated dynamic assembly using a publishing engine.
We will describe how you can get started with structured writing without knowing XML or installing anything.
The promise of topic-based structured authoring is not simply better documentation. It is the creation of mission-critical information for your organization, written with a deep understanding of your most important audiences, that can be repurposed to multiple delivery channels and localized for multilingual global markets. You are not just writing content, you are preparing the information deliverables that enhance the value of your organization in all its markets.
To do that well, you must understand the latest tools in structured writing that are revolutionizing corporate information systems - today in documentation but tomorrow throughout the enterprise, from external marketing to internal human resources. Whether you are trying to push a new product into a new market or are “onboarding” a new employee, the need for high quality information to educate the customer or train the new salesperson is a challenge for technical communicators. You need to think outside the docs!
The key idea behind Darwin Information Typing Architecture is to create content in small chunks or modules called topics. A topic is the right size when it can stand alone as meaningful information. Topics are then assembled into documents using DITA maps, which are hierarchical lists of pointers or links to topics. The pointers are called “topicrefs” (for topic references).
Think of documents as assembled from single-source component parts. Assembly can be conditional, dependent on properties or metadata “tags” you attach to a topic. For example, the “audience” property might be “beginner” or “advanced.”
At a still finer level of granularity, individual elements of a topic can also be assigned property tags for conditional assembly. More importantly, a topic element can be assigned a unique ID that makes it a content component reusable in other topics.
As you will learn, DITA is a leading technology for “component content management,” which multiplies the value of your work. You need to leverage DITA and structured content to multiply your income.
Slides from the Structured Authoring Workshop at TC Camp 2014 by Tracy Baker, Amy Bowman, and Wendy Shaffer.
The road from traditional book-based authoring to DITA and topic-based authoring is full of potholes.
How do you chop up a book into self-contained topics and put it back together into something that makes sense?
How do you handle reuse and linking?
And how do you wrap your mind around new tools and workflows while still getting your job done?
Three people who have made the trip share their experiences and lessons-learned to help you get to DITA/TBA without taking too many wrong turns.
Whether it's for your company or your own professional development (or ideally both), everyone should have a technology roadmap. Unfortunately there is no easy path to pre-made wisdom here, but this talk opines on some ideas and approaches to help formulate a roadmap that is relevant, pragmatic and importantly, able to be communicated to others.
Presented at Mastering SAP Technologies 2016
That is what we presented at the last Minibar here in London on April 25th. It took place at Corbet Place Bar at the entrance of the Trueman Brewery on Friday. Thanks to Christian for organising this great event.
Painless XML Authoring?: How DITA Simplifies XMLScott Abel
Presented at DocTrain East 2007 by Bob Doyle, DITA Users -- This introduction to XML Authoring will acquaint you with over fifty tools aimed at structuring content with DITA. They are not just DITA-compliant authoring tools (editors) for writers. They also include content management systems (CMS), translation management systems (TMS), and dynamic publishing engines that fully support DITA. You will also need to know about tools that convert legacy documents to DITA and help to design stylesheets for DITA deliverables. The best DITA tools for technical communicators implement the DITA standard while hiding all the complexity of the underlying XML (eXtensible Markup Language).
As a tech writer and not a tech, you should be able to forget about XML - except to know that you are using it (DITA is XML) and that it consists of named content elements (or components) with attributes. You need to know enough about the content elements so you can reference (conref) them for reuse. You need to know about their attributes so you can filter on them for conditional processing. And you should appreciate that because components are uniquely identifiable they lend themselves perfectly to automated dynamic assembly using a publishing engine.
We will describe how you can get started with structured writing without knowing XML or installing anything.
The promise of topic-based structured authoring is not simply better documentation. It is the creation of mission-critical information for your organization, written with a deep understanding of your most important audiences, that can be repurposed to multiple delivery channels and localized for multilingual global markets. You are not just writing content, you are preparing the information deliverables that enhance the value of your organization in all its markets.
To do that well, you must understand the latest tools in structured writing that are revolutionizing corporate information systems - today in documentation but tomorrow throughout the enterprise, from external marketing to internal human resources. Whether you are trying to push a new product into a new market or are “onboarding” a new employee, the need for high quality information to educate the customer or train the new salesperson is a challenge for technical communicators. You need to think outside the docs!
The key idea behind Darwin Information Typing Architecture is to create content in small chunks or modules called topics. A topic is the right size when it can stand alone as meaningful information. Topics are then assembled into documents using DITA maps, which are hierarchical lists of pointers or links to topics. The pointers are called “topicrefs” (for topic references).
Think of documents as assembled from single-source component parts. Assembly can be conditional, dependent on properties or metadata “tags” you attach to a topic. For example, the “audience” property might be “beginner” or “advanced.”
At a still finer level of granularity, individual elements of a topic can also be assigned property tags for conditional assembly. More importantly, a topic element can be assigned a unique ID that makes it a content component reusable in other topics.
As you will learn, DITA is a leading technology for “component content management,” which multiplies the value of your work. You need to leverage DITA and structured content to multiply your income.
Slides from the Structured Authoring Workshop at TC Camp 2014 by Tracy Baker, Amy Bowman, and Wendy Shaffer.
The road from traditional book-based authoring to DITA and topic-based authoring is full of potholes.
How do you chop up a book into self-contained topics and put it back together into something that makes sense?
How do you handle reuse and linking?
And how do you wrap your mind around new tools and workflows while still getting your job done?
Three people who have made the trip share their experiences and lessons-learned to help you get to DITA/TBA without taking too many wrong turns.
Whether it's for your company or your own professional development (or ideally both), everyone should have a technology roadmap. Unfortunately there is no easy path to pre-made wisdom here, but this talk opines on some ideas and approaches to help formulate a roadmap that is relevant, pragmatic and importantly, able to be communicated to others.
Presented at Mastering SAP Technologies 2016
Session at tcworld 2016. Organized by Kristen James Eberlein (Eberlein Consulting LLC); other participants were Joe Gollner (Gnostyx), George Bina (SyncroSoft), Jean-François Ameye (IXIASOFT), and Eliot Kimber (Contrext).
Describes the philosophical, programming, methodology, and business standards needed to keep technical communication current in an increasingly technical era.
Builder.ai Founder Sachin Dev Duggal's Strategic Approach to Create an Innova...Ramesh Iyer
In today's fast-changing business world, Companies that adapt and embrace new ideas often need help to keep up with the competition. However, fostering a culture of innovation takes much work. It takes vision, leadership and willingness to take risks in the right proportion. Sachin Dev Duggal, co-founder of Builder.ai, has perfected the art of this balance, creating a company culture where creativity and growth are nurtured at each stage.
Generative AI Deep Dive: Advancing from Proof of Concept to ProductionAggregage
Join Maher Hanafi, VP of Engineering at Betterworks, in this new session where he'll share a practical framework to transform Gen AI prototypes into impactful products! He'll delve into the complexities of data collection and management, model selection and optimization, and ensuring security, scalability, and responsible use.
Observability Concepts EVERY Developer Should Know -- DeveloperWeek Europe.pdfPaige Cruz
Monitoring and observability aren’t traditionally found in software curriculums and many of us cobble this knowledge together from whatever vendor or ecosystem we were first introduced to and whatever is a part of your current company’s observability stack.
While the dev and ops silo continues to crumble….many organizations still relegate monitoring & observability as the purview of ops, infra and SRE teams. This is a mistake - achieving a highly observable system requires collaboration up and down the stack.
I, a former op, would like to extend an invitation to all application developers to join the observability party will share these foundational concepts to build on:
A tale of scale & speed: How the US Navy is enabling software delivery from l...sonjaschweigert1
Rapid and secure feature delivery is a goal across every application team and every branch of the DoD. The Navy’s DevSecOps platform, Party Barge, has achieved:
- Reduction in onboarding time from 5 weeks to 1 day
- Improved developer experience and productivity through actionable findings and reduction of false positives
- Maintenance of superior security standards and inherent policy enforcement with Authorization to Operate (ATO)
Development teams can ship efficiently and ensure applications are cyber ready for Navy Authorizing Officials (AOs). In this webinar, Sigma Defense and Anchore will give attendees a look behind the scenes and demo secure pipeline automation and security artifacts that speed up application ATO and time to production.
We will cover:
- How to remove silos in DevSecOps
- How to build efficient development pipeline roles and component templates
- How to deliver security artifacts that matter for ATO’s (SBOMs, vulnerability reports, and policy evidence)
- How to streamline operations with automated policy checks on container images
UiPath Test Automation using UiPath Test Suite series, part 3DianaGray10
Welcome to UiPath Test Automation using UiPath Test Suite series part 3. In this session, we will cover desktop automation along with UI automation.
Topics covered:
UI automation Introduction,
UI automation Sample
Desktop automation flow
Pradeep Chinnala, Senior Consultant Automation Developer @WonderBotz and UiPath MVP
Deepak Rai, Automation Practice Lead, Boundaryless Group and UiPath MVP
The Art of the Pitch: WordPress Relationships and SalesLaura Byrne
Clients don’t know what they don’t know. What web solutions are right for them? How does WordPress come into the picture? How do you make sure you understand scope and timeline? What do you do if sometime changes?
All these questions and more will be explored as we talk about matching clients’ needs with what your agency offers without pulling teeth or pulling your hair out. Practical tips, and strategies for successful relationship building that leads to closing the deal.
LF Energy Webinar: Electrical Grid Modelling and Simulation Through PowSyBl -...DanBrown980551
Do you want to learn how to model and simulate an electrical network from scratch in under an hour?
Then welcome to this PowSyBl workshop, hosted by Rte, the French Transmission System Operator (TSO)!
During the webinar, you will discover the PowSyBl ecosystem as well as handle and study an electrical network through an interactive Python notebook.
PowSyBl is an open source project hosted by LF Energy, which offers a comprehensive set of features for electrical grid modelling and simulation. Among other advanced features, PowSyBl provides:
- A fully editable and extendable library for grid component modelling;
- Visualization tools to display your network;
- Grid simulation tools, such as power flows, security analyses (with or without remedial actions) and sensitivity analyses;
The framework is mostly written in Java, with a Python binding so that Python developers can access PowSyBl functionalities as well.
What you will learn during the webinar:
- For beginners: discover PowSyBl's functionalities through a quick general presentation and the notebook, without needing any expert coding skills;
- For advanced developers: master the skills to efficiently apply PowSyBl functionalities to your real-world scenarios.
Encryption in Microsoft 365 - ExpertsLive Netherlands 2024Albert Hoitingh
In this session I delve into the encryption technology used in Microsoft 365 and Microsoft Purview. Including the concepts of Customer Key and Double Key Encryption.
Elevating Tactical DDD Patterns Through Object CalisthenicsDorra BARTAGUIZ
After immersing yourself in the blue book and its red counterpart, attending DDD-focused conferences, and applying tactical patterns, you're left with a crucial question: How do I ensure my design is effective? Tactical patterns within Domain-Driven Design (DDD) serve as guiding principles for creating clear and manageable domain models. However, achieving success with these patterns requires additional guidance. Interestingly, we've observed that a set of constraints initially designed for training purposes remarkably aligns with effective pattern implementation, offering a more ‘mechanical’ approach. Let's explore together how Object Calisthenics can elevate the design of your tactical DDD patterns, offering concrete help for those venturing into DDD for the first time!
Transcript: Selling digital books in 2024: Insights from industry leaders - T...BookNet Canada
The publishing industry has been selling digital audiobooks and ebooks for over a decade and has found its groove. What’s changed? What has stayed the same? Where do we go from here? Join a group of leading sales peers from across the industry for a conversation about the lessons learned since the popularization of digital books, best practices, digital book supply chain management, and more.
Link to video recording: https://bnctechforum.ca/sessions/selling-digital-books-in-2024-insights-from-industry-leaders/
Presented by BookNet Canada on May 28, 2024, with support from the Department of Canadian Heritage.
SAP Sapphire 2024 - ASUG301 building better apps with SAP Fiori.pdfPeter Spielvogel
Building better applications for business users with SAP Fiori.
• What is SAP Fiori and why it matters to you
• How a better user experience drives measurable business benefits
• How to get started with SAP Fiori today
• How SAP Fiori elements accelerates application development
• How SAP Build Code includes SAP Fiori tools and other generative artificial intelligence capabilities
• How SAP Fiori paves the way for using AI in SAP apps
1. DITA Best Practices
Alan Houser
Principal Consultant and Trainer
Tel: 412-363-3481
arh@groupwellesley.com
Group Wellesley, Inc. www.groupwellesley.com
2. About Me
• Consultant and Trainer in Publishing Tools and
Technologies
• Member OASIS DITA Technical Committee
• Society for Technical Communication, Liaison to the
World Wide Web Consortium (W3C)
• Fellow, Society for Technical Communication
• Candidate for Vice President, Society for Technical
Communication, 2011-2012
3. DITA in Context
• Developed by IBM corporation as a
successor/replacement for IBMIDDoc (a “book-centric”
information model).
• Donated by IBM to OASIS (Organization for the
Advancement of Structured Information Standards).
• DITA 1.0 finalized by DITA Technical Committee February
2005, formally approved by OASIS June 2005.
• DITA 1.1 approved by OASIS August 2007.
• DITA 1.2 approved by OASIS December 2011.
4. Best Practices for Discussion
• Start with audience and task analysis
• Write for re-use
• Embrace minimalist principles
• Include human editorial control in your workflow
• Use best practices when migrating legacy content
• Manage boilerplate content and string replacement
values
6. First Rule of Technical Communication
Know your audience!
7. Best Practice #1: Start with careful
analysis of your audience and tasks
Many people are first exposed to DITA through the
standard topic types of task, concept, and reference.
They are tempted to begin by writing topics.
Any DITA scenario should begin with a careful audience
and task analysis.
Formalize the analysis in a DITA map.
Then write topics to populate the map.
8. Techniques for Audience and Task
Analysis
Persona
• Short description of a typical reader.
• Can be several sentences, typically a paragraph or two.
• Your audience is probably not “anybody”, even if you
think it is.
• For most products and services, 3 – 5 personas are
sufficient
9. Example Persona
John is a an administrator at a regional hospital. He
has 2 years of college, and is proficient with Microsoft
Office products. Once/month, he uses the Acme2010
Audit Software to generate a report of hospital bed
usage. He does not use Acme2010 Audit Software at
any other time, for any other task.
10. Techniques for Audience and Task
Analysis
Task Analysis: One Technique
Card sorting
• “Brainstorm” to discover typical user tasks.
• Write each task on a note card.
• Sort the note cards. Categories should reveal
themselves.
• Use the cards to define your topics.
• Use the categories and organization to define
your map.
11. Best Practice #2: Write for Reuse
Tip: Omit details except when necessary, especially when
details may vary across related products.
Examples:
Remove the five cover screws.
Remove the cover screws.
Enter your password on the backlit keyboard.
Enter your password.
Press the green button to start a call.
12. Best Practice #2: Write for Reuse
Tip: Avoid inline cross-references. Use DITA relationship
tables to generate list of related topics.
Example:
Learn about video in Playing Video on your Cell Phone.
What if you generate content for a model that does not
support video? The link is broken or suppressed.
Learn about video in .
13. Best Practice #3: Embrace Minimalist
Principles
• Roots of DITA:
minimalist
approach
14. Best Practice #3: Embrace Minimalist
Principles
Tip: A DITA topic should express a single idea, and be
usable stand-alone.
Tip: DITA does not support stem sentences. They are
considered unnecessary in topic-oriented publishing.
15. Best Practice #3: Embrace Minimalist
Principles
Stem Sentences
Changing your battery
To change your battery, you should do the following:
1. Remove the cover.
2. Remove the battery.
16. Best Practice #3: Embrace Minimalist
Principles
Stem Sentences
Changing your battery
1. Remove the cover.
2. Remove the battery.
17. Best Practice #3: Embrace Minimalist
Principles
Tip: Use the DITA <shortdesc> element to describe your
topic, to aid user navigation and improve findability.
The <shortdesc> element appears after the <title> and
before the <body> content. It is considered both content
and metadata. It should be a short (1-2 sentence)
description of the topic.
The <shortdesc> text is rendered as preview and hover-
over text.
18. Best Practice #4: Don’t forget editorial
quality control
A well-defined quality-control process becomes even more
important in the context of distributed topic-oriented
authoring. Be sure to include the review of human
editors and reviewers in your workflow.
19. Best Practice #5: When starting, put
aside legacy content
It is natural to want to begin a DITA migration by converting
legacy content to DITA.
If you take this approach, the result is the same legacy
content, with only a subset of DITA benefits.
Go to your legacy content only after you have completed
an audience and task analysis, and have developed your
DITA information architecture.
20. Best Practice #6: Manage reusable
content chunks
Tip: Maintain boilerplate text and variable string
replacements in special-purpose topics.
Examples:
• Admonishments (notes, cautions, warnings)
• Legal text
• Variable string substitution
21. Best Practice #6: Manage reusable
content chunks
Tip: DITA referencing, inclusion, and linking is based on
<filename> and <id>. Unlike most XML-based publishing
architectures, <id> values need not be unique across
document sets. Use this feature to label reusable chunks
of content.
22. Best Practice #6: Manage reusable
content chunks
Tip: Use DITA conrefs or conkeyrefs to maintain variable
text.
Tip: Use DITA filtering attributes to control replacement
text.
23. Best Practice #6: Manage reusable
content chunks
Tip: Use DITA 1.2 keyrefs to ease maintainability of
references (conrefs, topicrefs) and improve the authoring
experience.
<ph conref=“reusableText/variables_nokia.xml#Brand” />
<ph conref=“Phone/Brand” />
24. Contact Us!
We hope you enjoyed this presentation. Please feel free to
contact us:
Alan Houser
arh@groupwellesley.com
Group Wellesley, Inc.
933 Wellesley Road
Pittsburgh, PA 15206
USA
412-363-3481
www.groupwellesley.com