XML Documentation Add-On for Adobe Experience Manager – First Impressions

Posted on by Marina

I’m going to start using the XML documentation add-on for Adobe Experience Manager and say goodbye to MadCap Flare soon.

The XML documentation add-on for Adobe Experience Manager is an end-to-end component content management system for structured content, that is built upon Adobe Experience Manager, a CMS.

To prepare for this new tool, I’ve been reading articles and watching videos to dive into the topic. My first impressions so far have been very positive, I’ll use this article to collect my thoughts on it.

This is what I like about the tool:

– All content can be stored centrally in the Assets component. Adobe has built a lot of capabilities targeted at technical writers:
o A DITA Web Editor
o Review & approval collaborative tool – dev, PM, support, etc. can provide feedback and help to improve the content.
o Reporting capabilities – helps you check the readiness of the content.
o Translations are processed automatically. You can say goodbye to manual tedious processes (to a certain extent, of course). The content is automatically pushed to a translation vendor when the topic is updated. Then, you can re-import the translated content, and eventually review and approve it.
o Publishing tool (online, PDF, more formats)
o If you have Adobe Analytics, you can get more information about usage.
– The add-on can be integrated into DITA authoring tools, for example, FrameMaker.
– The user interface is user-friendly and intuitive.
– You can check out topics for editing, which prevents conflicts (no more merges in GIT!)
– AEM has its own version control system. When you have finished editing a topic, you can simply “save the revision” to create a new version of the xml. You can also add a comment to help you track your changes. AEM allows you to compare two versions and revert the content to a previous one. You can see the current version of a topic at the upper-right corner.
– When you edit a topic, you can see the context in which it is inserted.
– AEM has a graphical interface (Author view). You are not presented with a lot of tags. You can also change the view to code editor, which is context-aware. That is, the editorgives you a list of supported elements that can be used in the context, based on the previous and following element.One more good thing about the editor is that it identifies and flags syntax code errors (real-time validation).
– The breadcrumbs are also an advantage. In MadCap Flare, you need to hover over the topic title to see the path.
– A nice feature compared to MadCap is that you can edit all the elements included in a topic without having to open them, selecting them is enough.
– The buttons in the toolbar are the standard ones: list, paragraphs, links and so on. The good news is that the toolbar can be extended and customized to your needs, which is great, especially when it comes to using specific styles.
– Conditions are supported. They are set as style “attributes”;that is, you can define the audience, status, etc… for your content.
– You can filter the preview by audience and products. I still need to find out how to filter by version.
– Creating content from scratch is very easy. You can select what kind of content you’d like to create from a list of templates. If you select DITA topic, you can also select the template you want to base your topic on: topic, task, content, reference or ditaval. Additionally, you can create “custom templates” for, for example, subject-matter experts who are not familiar with DITA but would like to add some information to the documentation. You can send them an e-mail containing a task to create documentation for a particular topic. They don’t see the DITA format, but a very intuitive user interface similar to Word.
– The content of snippets in MadCap Flare is also valid for AEM. In AEM, this concept can be set as conrefs or keys.“Snippets” don’t have a different format in AEM, all the topics are .xml, but the type of element that can be re-used is p (not topic). Reused content is displayed in blue. (<p conref=”link”></p>)
– Topics cannot be inserted as weblinks, but only as content reference. This prevents a lot of problems while moving & renaming concepts, because xrefs are always updated.
– You can also create e-mail links
– You can set language properties to identify the language in which the topic is written.

A technical writer’s journey to SAFE

Posted on by Marina

Last year my company adopted SAFE, a new working methodology to enhance alignment, collaboration, and delivery for multiple Agile teams. We were all excited and curious about this new approach. SAFE would allow us to communicate better, anticipate bottlenecks and prevent unexpected dependencies that caused many issues in the past.

The documentation team was also eager to know more about SAFE. It would be the next stepping stone to optimize our involvement with the teams and raise the quality and user-friendliness of the documentation. SAFE would allow us to get accurate information earlier and to create a commitment plan to better manage our workload.

Although this methodology has proven to be very successful, we soon realized that it lacks information on how technical writers should interact with other team members and prepare for the PI, or the role they play during the event and on how to participate in the PI execution. In fact, the official SAFE site contains only one reference to technical writers: we are “potential members of shared services”. The trainers provided us with a lot of information on what to do and when, but these guidelines are missing from the official SAFE documentation.

During the last years, our team has come a long way to boost our visibility and the general perception of our value for the company. The progress has been remarkable. We are now present in all important meetings, collaborate regularly with all stakeholders and receive valuable feedback from support, pre- and post-sales, product management and end users on how to improve the documentation, and consequently customer satisfaction.

To make up for the lack of guidelines, we decided to define our own best practices to work in SAFE:

Step 1: The documentation for each PI plan is organized within a dedicated EPIC, and each task is linked to the corresponding DEV issue

Documentation is not a dependency for the development teams, it is part of development. During the PI planning, we identify which stories need to be documented and flag them. Then, we create a documentation EPIC and tasks for every story that requires documentation. Finally, we link the documentation tasks to the development tasks.

This approach has several advantages: on the one hand, the development teams know at a glance if documentation will be provided for a story, the progress of the tasks, and they can also review the new content by clicking on the internal link to the latest version of the documentation (included in the documentation task and only available for internal users). On the other hand, technical writers can keep track of the progress of the dev tasks and start working on the documentation as required.

Step 2: The documentation team is also a development team.

Technical writers do much more than documenting features. We talk to customers, create training materials, curate texts, continuously improve/update existing information, work on standards and guidelines, help define UI text, review system/error messages, create videos and so on. On top of that, we document features for new releases and work very closely with development teams located in different countries. We also need to learn new things on a daily basis to keep up with development and describe processes and practices in the best possible way. All this effort needs to be visible.

To showcase it, we create a PI plan for the documentation team (which contains additional tasks from those created to document dev stories) and present it in front of all teams that are part of the release train. The time allotted for these “extra tasks” depends on the number of tasks created to document new features.

Step 3: Technical writers ensure message consistency

Technical writers act as gatekeepers for text quality and uniformity of the user stories. We work closely with the Product Owners and UX designers to help define the text displayed in the user interface. We suggest enhancements, proofread existing content and align the UI with the user documentation to ensure product consistency.

With these simple three steps we established our place in SAFE and successfully integrated and supported the teams to develophigh-quality software.

These questions can help you estimate the time you will need to complete a documentation project.

Posted on by Marina

On average, documentation accounts for approx. 10% of the effort in a software project, meaning that documentation plays a crucial role in the overall cost. Estimating the time and effort a documentation project will take is no mean feat, but you can use some metrics to help you give a ballpark figure.

Although methods for time estimating already exist (e.g. top-down, bottom-up design, minutes/hours design), too many factors may come into play and affect the original estimate. Answering the following questions can make your estimate more accurate and well-grounded:

  • Are there any existing tech specs to support the creation process of the documentation?
  • Are graphics, screenshots or videos needed?
  • How many writers can take part in the project? How much time can each of them devote to it? How much experience do they have?
  • How complex is the project? Are the writers involved in the project subject matter experts or will they have to invest time in learning the tool/technology used?
  • Are the people who can provide the necessary information to the writers available at that point in time? How many meetings will have to take place?
  • How many tasks are needed?
  • Are you going to create a new manual from scratch or do you have to update an  existing version of the documentation?

Using a planing tool can help you estimate future projects based on the duration of previous ones. You can compare planned and actual estimates and analyze the factors that caused your project to take longer than expected. A planing tool can also help you justify the time and resources needed to complete the project.

De media, la documentación supone un 10% del esfuerzo de un proyecto de software, por lo que las estimaciones para su realización tienen una gran importancia en el coste final del mismo. Estimar el tiempo y esfuerzo que te llevará realizar un proyecto no es una tarea fácil, No obstante, puedes utilizar algunos parámetros que te ayudarán a calcular un dato aproximado. 

Aunque ya existen algunos métodos para la estimación temporal de un proyecto de documentación (por ejemplo, diseño arriba-abajo/abajo-arriba o minutos/horas), son muchos los factores que pueden entrar en juego y afectar a la estimación inicial. Responder a las siguientes preguntas puede hacer tu estimación más precisa: 

  • ¿Existen especificaciones técnicas que puedan ayudar en la creación de la documentación?
  • ¿Es necesaria la creación de gráficos, pantallazos o videos?
  • ¿Cuántos redactores pueden participar en el proyecto?¿Cuánto tiempo puede dedicar al proyecto cada uno de ellos?¿Cuánta experiencia tienen?
  • ¿Qué complejidad tiene el proyecto? ¿Los redactores involucrados en la materia son expertos en el tema o tienen que invertir tiempo en aprender a utilizar la herramienta/la tecnología?
  • ¿Qué disponibilidad tienen las personas que pueden proveer información a los redactores?¿Cuántas reuniones deberán celebrarse?
  • ¿Cuántas tareas son necesarias?
  • ¿La tarea consiste en crear un nuevo manual desde cero o tan sólo es necesario actualizar una versión existente de la documentación?

Utilizar una herramienta de planificación puede ayudarte a hacer una estimación de proyectos futuros, ya que podrás basarte en la duración de proyectos anteriores. Puedes comparar estimaciones planificadas con las reales y analizar los factores que causaron un retraso en el proyecto. Una herramienta de planificación también te puede ayudar a justificar el tiempo y los recursos necesarios para completar el proyecto.

 

Technical Writing

Posted on by Marina

– Hi! What do you do?

– I’m a technical writer.

– Ah, ok! (No idea what she really does, he thought).

When having a conversation with someone for the first time, I always love to see his/her face when talking about my job. When I see a gaze of perplexity (which is quite common) I use to put it simply: I write instructions to help people learn how to use something.

Yes, I know, this may be an inaccurate description of my everyday activities, but it works. A usual reaction is:

– Oh, I see! You write these instructions nobody really cares about until something doesn’t work anymore or they can’t figure out by themselves what to do next.

– Well, actually, the right way to go would be to read the documentation before…Anyway, now you know what I do 🙂

Joking aside, to me technical writing means much more. When I write, my main goal is to help people find solutions to problems. I don’t mean to teach anybody (although I love teaching) but to help them fix what’s wrong or just show them how to use something they need in a clear and concise way.

What I really love from technical writing is the “how”. How to get the necessary information from developers, understand and organize it, how to write good examples to improve understanding, how to create supporting graphics, how to understand the customer needs and provide the type of information they really want…and of course how to translate the English text into other languages for an audience with a very different background. That’s challenging but also a lot of fun!

(Spanish version below)

Continue reading Technical Writing