A technical writer’s journey to SAFE

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.

PowerPoint Karaoke 🎤

I’m curious by nature and I’m always looking for new ways to meet interesting people. This year I’m a mentee at the mentoring program of the professional Women’s Network of Vienna. I’d recommend it to everybody (not only women) who is willing to achieve professional and/or personal goals. I’ll write a post about my experience later.

Participating in this program has given me the opportunity  to meet amazing people who want to grow and self develop (a topic that I love and practice on a daily basis). J is one of them. She decided to organize a get together in January, where some of the mentees shared their experiences about the program, gave each other tips, recommended books and drank coffee. J and I connected immediately. We started talking on how to give something back to the people who organize the program and to all participants, since we are both very grateful about how much we are learning (the program is free, mentors are volunteers), and she told me about some “karaoke sessions” (powerpoint presentations) that are organized in Vienna for people who are afraid of speaking in public. I really loved the concept and we started to think about how to adapt it to our needs. The idea we came up with consists of stepping up to a stage and talk in front of a respectful and supportive audience (mainly other mentees and mentors) who will give constructive feedback to improve the way we communicate. We agreed to meet again to further develop the idea and add an important element when it comes to keep your nerves under control: improvisation.

To add more fuel to the fire, we decided to provide the presentations to the speakers on the stage. That means, they have no time to prepare! They will see each slide at the same time as the audience does.

The event takes place today. We have collected several presentations about different topics, from food to technology, which will be assigned randomly to the presenters.

When we posted the event on social media or talked about it in some of our meetings, the response was always the same: -omg! I really like the idea, I get so nervous when I have to speak in public! –

It turns out, Glossophobia or speech anxiety is listed as American’s number one fear. Even before death! See: http://westsidetoastmasters.com/resources/off_the_cuff/chap1.html.

People have signed up for the event for two main reasons: first, because they like challenges, and second (but not less important), because we have removed judgement from the equation. Only constructive feedback is allowed and we will all be in the same situation, that is, on the stage, which means, everybody will empathize with the presenter.

I’m looking forward to this evening!

About Chatbots

One of the projects I want to carry out this year is the development of a documentation-based chatbot to help readers find the information they need, without having to click on several search results (sometimes inaccurate) provided by search engines. To this end, I’ve been reading different articles to learn more about existing technologies and to assess which one fits best to the content I write.

During the “100 days of code” challenge I took up last year, I also learnt about the history of chatbots. It turns out, chatbots are not really that modern (at least, the concept). The first chatbot, ELIZA, was created in 1966 by Weizenbaum. ELIZA impersonated a psychotherapist whose treatment was, let’s say, not very effective 😊. To understand the logic behind it, I tried to create my own psychotherapist bot some months ago (I called it Freud, of course). If you’re interested, you can check it out here: https://github.com/marinahgtech/BotTherapist

Chatbots make interactions with content more human, since the user accesses the content by answering the bot’s questions. The information displayed is determined by the answer provided. Chatbots also leverage the daily work of other stakeholders, like support professionals and consultants, especially when they have to work with complex products. The chatbot helps them find the right content faster, which saves time.

Chatbots usually make use of retrieval models. To put it simply, these models consist of predefined pairs of questions and answers. Some companies have been introducing NLP and deep learning technologies for some years now to offer and almost human interaction between the user and the chatbot (the idea is that, at some point, humans cannot tell if they’re talking to a person or a machine). This is a very ambitious approach, that would be nice to have for us in the near feature. But first, I want to focus on building a basic retrieval model. I’m fascinated about natural language processing anyway, and learning more about it is on my bucket list. I’m starting a Python course as a preparation for an NLP course I want to take this summer.

Turning to the matter in hand: retrieval-based models use a repository of q&a pairs and allow to choose the right answer based on the human’s input. This is all based on heuristics, the function that determines which answer should be retrieved. Machine learning classifiers could be also used to pick up the right answer, but for the sake of simplicity (and feasibility), I’ll start with the simplest model first. This includes short conversations and a closed domain (which, by the way, fits perfectly with the customer needs to find technical information for a certain product).

The retrieval-based model has some limitations, the most important one being the fact that the number of predefined responses is very reduced, but it’s a good place to start for newbies 🙂

I’ll keep you posted on my progress…

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

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 editor gives 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.

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

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

– 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