Romania

 

Presentations

Using DITA for Software Documentation
George Bina, Syncro Soft

In today's quickly changing environment the need to present content in new and various ways appears very frequently so it becomes more and more important to have your information encoded in a standard open format separated from a specific presentation form.
From the available standards, DITA has a privileged position as it managed to form a very active community around it with many offers for authoring, content management, publishing,translation management, etc. That means you have many options and there is no vendor lock-in, your options range from building your own or using open source and free tools to taking advantage of turn-key solutions and anywhere in between.
While DITA is a platform on which you can define your own document types, it comes also with ready to use support for product, technical and software documentation. Software companies already use a number of tools for managing the software development process and the same tools can be used also for the software documentation. More precisely, the documentation process can be closely integrated with the software development process and we can take advantage of existing systems that are used for issue tracking and version management.

You will be able to see how we use DITA to manage software documentation, integrating the documentation into our software development process, and how we produce more than 15 deliverables from the same source to support 3 related software products.This is an example that you can easily adapt and adopt into your own company to cut down the costs and improve the quality of your software documentation.

Spice up Your DITA Workflow
Magda Caloian, Dolby Laboratories

Sometimes it feels like the only constant in a technical writer's work is change. Whether in agile or waterfall, project teams tend to place documentation towards the end of the process, or leave them at least one iteration behind. So after documentation is reviewed, approved, integrated in the kit and sent to translation, you notice the final seasoning: "minor" changes in the product right before the release. A modified label here, a moved button there... are exceptions to the "code freeze".
But change is good, and you're already at great advantage if using DITA. Indeed, you can make your documentation flexible and agile, by adding a few scripts to your DITA projects, to keep up with the changes in the products you are documenting.

Let's see some examples for frequent updating of:

  • strings in the user interface
  • reference code
  • application screenshots
  • in-line code documentation

In the case of GUI strings, you can use keys in DITA, so that you wouldn't have to worry about changes in all the topics. You just update the values in a keymap, or even use different keymaps in the same project, for different versions of the product. The special spice would be generating the keymaps on the fly, and we'll go through an example for this case.
Keeping sources like the code samples, or 3rd-party licenses, in separate files, allows you to integrate them in your DITA content with coderef, increasing the flexibility of your projects.
If you are using screenshots in your documentation, it is also best practice to refer to them by keys. Thus you can have separate sets of images for various product flavours and languages. Imagine you could even have the screenshots generated automatically. Wouldn't that save a great deal of time?
Another advantage with DITA is you can apply an XSLT transformation of the in-line code documentation written by developers, like for example Python docstrings in rST, and even do the round-trip between rST and DITA formats. This method allows developers to keep writing in their favourite environment and you can even supply edited versions back to them in the same form.
With these few seasoning ideas for your DITA workflows, you can save a lot of time and frustration when updating documentation projects, and you increase their accuracy and consistency. Give it a try!

Get everyone involved: Technical Documentation with Wikis
Johannes Egenolf, K15t Software GmbH
A growing number of companies worldwide and across all industry sectors already create and share their knowledge with enterprise wikis like Atlassian Confluence. Those knowledge management and collaboration systems enable all employees to create and access content within the same tool. Collaborative documentation workflows and flexible tools are becoming crucial to keep up with the pace of agile product development.
Because technical documentation is a major corporate content asset, more and more organizations start using wikis also as a techcomm tool. Their main goals are to improve collaboration when producing documentation, to unify the content management toolchain, and to simplify the authoring and distribution workflow.
 
In this session, we will discuss use cases where Confluence might be the right choice. We will bust some common myths about wikis and their content management and single-source publishing abilities nowadays. Also there will be room for questions.

Contents:

  • What is an enterprise wiki?
  • Use-cases for wiki-based documentation
  • Agile documentation workflows
  • A wiki's collaboration strengths and potential flaws
  • Workflow management and content lifecycle in a wiki
  • Content distribution and single-source publishing
  • Common myths about wiki-based documentation
  • Takeaways and Q&A panel
Working with Collaborative Tools as a Reviewer and as a Terminologist
Patricia Comanescu, Frequentis
Frequentis AG is a company specialized in communication solutions for security purposes in the fields of air traffic control, maritime traffic control, defense, public safety and transport. Because of its very targeted expertise field and due to its global presence, the documentation needs of the company are huge, as it is its concern for consistency of the documentation terminology and style, as well as for the assurance of the quality of its documentation.
Solution to this – a specific content strategy: a dedicated technical communication and information team (TCI) and internal tools which allow collaboration at any stage of the processes: creation or revision of documentation/code.
Among the collaborative tools the company uses: JIRA, an internal knowledge base, an internal wiki –and, Revsys – an internal tool for code and documentation collaborative revision.
My role was to create an internal glossary, quick and easy to use, to address specific terminological needs for the dev and tester teams working on air traffic control. The glossary explains and defines  the acronyms of frequent terms used in ATC. I used a collaborative software - mediawiki – to create a page whose visual was familiar, which could be accessed on the wiki page of the company and which was linked to the dev projects posted on the internal wiki. I preferred a tabular form, familiar for a dev or a tester. I gave the acronyms in English and French, their long form, their definition and other authoritative sources of information. The wiki glossary is open to the users' suggestions to introduce new terms.
On the other hand I worked extensively as a reviewer with Revsys, an internal revision tool which comprises a common server where the document to review is uploaded and downloaded together with its revised versions. It also implies a complex team of reviewers (technical and linguistic), a project manager of the revision, a project manager for the project the documentation is linked to. It is based on an database with  an appropriate interface for introducing the comments and a scale to classify the importance of the errors. The database can then be queried via filtering tools, as it enables you to filter the revisions by number, by project, by author, moderator, etc. It is equally a tool of quality assurance as you can apply quality criteria, included in checklists dedicated to the type of revision project: documentation, coding, testing.
Both collaborative tools present advantages and downturns for both the systems. The advantages are as follows: both enable a collaborative terminological and revision approach. They are accessible to the end-users. They involve specific expert actors who contribute to the quality of the terminology or of the revision. The downturns concern the length of the process in for Revsys, and the lack of visibility for the wiki glossary.
Multi³ – Multi-channel, Multi-lingual, Multi-usage of Content
Andrei Popa, euroscript international

Content is available in many different forms and many different languages within a company. The responsibility for content writing and structuring lies in the hands of different departments, follows different rules, has different goals, and yet it originates all around the same problem, describes the same products, explains the same processes, just in a different way.

For technical documentation the processes for content writing have been established within the last 10 years. Systems are available that support this process into the last detail, but what about producing marketing content? Where are the tools that support this process and where are the differences in the processes between marketing and technical documentation? Is there a common denominator linking the two processes? How can the two processes benefit from each other?

Our presentation will explain where content is used and how it can be shared; it will discuss all the channels that are relevant and must be considered; it will demonstrate the world of digital experience management with all his facets like social media, web experience or mobile solutions.
A special focus will be put on the question how to support the content creation process in view of the challenges of web experience management. We will show how content creation can be handled without buying one of the big, powerful yet expensive Marketing Resource Management systems and how you can combine content creation with localisation in an integrated approach in order to reduce the number of interfaces for the people responsible for the creation of the multi-language- content. And last but not least it will lead the way to a smoother integration of all collaborators within the complex process of marketing material production and planning.
We will show that supporting the processes of content creation and dissemination in the marketing environment leads to a significant increase of both efficiency and effectiveness, while at the same time reducing process complexity and making sure that your innovative data does not end up in the Big Data pools on the other side of the Atlantic, for re-use by “interested” third parties.

Our Sponsor for all cities

Supported by