Documentation Process

22 Nov

Documentation Development in Agile Development Models

Documentation Development in Agile Development Models

In the previous post, we discussed about the integration of Documentation Development Life Cycle (DDLC) with the Waterfall Model of Systems Development. Now that the software engineering is evolving to bring in more speed, efficiency, and tendency to provide quicker insights into the final outcomes, there are newer methodologies gaining popularity. Agile Development is one such approach that talks about having increments of working software developed in some defined time periods to give more clarity and garner confidence of developers and customers alike.

With the change in perspective, documentation development needs to change suit too. Let’s see how does the technical and user documentation get affected while progressing in an Agile fashion. To understand the change solicited by the Agile Development process, let us understand what it demands.

There are many Agile Development models such as Scrum, Extreme Programming, Agile Modeling and so on. For this post, I would consider Scrum model to explain Agile Development process.

The essence of Agile Development lies in more emphasis on collaboration, communication, incremental tangible outcomes, and active customer participation. However, it doesn’t completely ignore the importance and role of processes, documentation, and extensive planning. It puts more focus on what needs to be built rather than aggressively tracking how it is being built. Agile Development is all about being receptive to change and adapting quickly. It also puts more responsibility on team members to communicate, collaborate, give ideas, identify risks, propose solutions, set goals, prioritize tasks, and track the status for one’s work products.Image depicting the stages in an Agile Software Development model

To be precise, the Agile Development models split the main project objective or goal into small and smaller increments that would be developed over a number of time frames such as a week to a month, during the estimated project duration. For every defined cycle, also called a Sprint, each member has to identify his work product or software increment that is complete in a way and can be used.The tasks are identified in a very interesting manner by depicting them as “user stories” wherein a user should be able to use the work product to accomplish something.

Communication and collaboration take the center stage. The team meets before the start of every sprint to plan for it and then once again after they finish the sprint—to review the progress, challenges, risks, identify the lessons learned and the best practices for future. But that’s not all they have for communication and collaboration. They meet on a daily basis in a very short meeting that gives a chance to share about the progress, bottlenecks, and to plan when and where they can get help.

Transparency is the main keyword. All Agile Developments models ensure that all the team members know what the other person is doing. It helps in proper coordination and better planning.

So, the take away for the documentation engineers is:

The technical writers can see the bigger picture right through the beginning as they are included in the sprint planning meetings.

The technical writers get to interact with all team members or any specific member, who could help with the required information. This eases the requirement understanding and requirement gathering challenges.

At every change initiation, they get a chance to discuss the impact on documentation and plan for it in time.

The most important aspect for technical writers is time management and planning the activities that aren’t dependent on work product in any sprint. Some examples of such activities could be preparing templates or stylesheets, and so on. They have to ensure that they schedule such activities either in early sprints where there is more of analysis and design underway or whenever they finish their work product sooner in a sprint.

As for the Documentation Development Life Cycle (DDLC), it shrinks to fit in every single sprint and follows an iterative and incremental approach.

Overall, working in an Agile Development model gives more comfort, support, and visibility to the technical writers and they don’t seem to work out of an island.

By Documentation Development Life Cycle, Documentation Process, Documentation Project Management, Project Management, Technical Writing , , , , , , , , 0 Comments
Read more...
14 Nov

Mapping Documentation Development Life Cycle (DDLC) with SDLC

Software Development Life Cycle is a sequence of phases or logical stages in the course of development of an idea into a software application or a product. It is commonly abbreviated as SDLC. A well-known traditional approach to SDLC is known as Waterfall Model. The Waterfall Model lists the stages in the life cycle as:The_Waterfall_Model_software_engineering_ascezen

  1. Communication (Project Initiation, Requirements Gathering)
  2. Planning (Estimating, Scheduling, Tracking)
  3. Modeling (Analysis, Design)
  4. Construction (Code, Test)
  5. Deployment (Delivery, Support)

For any software application to be developed, the development team isn’t just constituted of software engineers, analysts, and architects. It also requires people to test and document the processes as well as the product. The group that works on creating and maintaining documentation is known as Documentation or Technical Publications group and it is composed of Technical Writers—people who can create Technical and User Documentation.

The Technical Writers also follow a development cycle for creating documentation, which is known as Documentation Development Life Cycle. The Documentation Development Life Cycle (DDLC) maps with the SDLC such that the entire product team works in close coordination to complete the development, adhering to a common project schedule. Modeled on SDLC, the DDLC has somewhat similar stages as that of SDLC. However, the duration of stages varies according to the difference in availability schedule of inputs for various stages. Let us begin with taking a look at the stages in the DDLC.

The DDLC stages, as understood by Technical Writing team at Ascezen, include the Image depicting stages of Documentation Development Life Cycle (DDLC)following:

  1. Understand Requirements
  2. Design
  3. Develop
  4. Review
  5. Finalize
  6. Publish

The activities to be performed during each of the stages are listed below:

  1. Understand Requirements
    • Understand the Product or Application to be developed
    • Gain an understanding of the Domain or Subject Matter
    • Understand Client Requirements for Documentation
    • Study Legacy Documentation and Writing Style Guides used by the Client
    • Provide Content Consulting or Evangelism
    • Propose Documentation Deliverables and Tools to be used
    • Prepare Effort Estimate
    • Propose Team Size and Composition
  2.  Design
    • Prepare Templates and Stylesheets
    • Prepare an Outline or the Table of Contents for documents to be created
    • Create Content Strategy for Single-sourcing or writing for multiple user roles
    • Create a Documentation Project Schedule
  3. Develop
    • Gather Information: Read Design Specifications ,Interview Subject Matter Experts (SMEs)
    • Create Content Drafts
    • Create and Insert Graphics
    • Format the Content
    • Generate Output(s)
  4. Review
    • Language Review
    • SME or Technical Review
    • Client POC’s Review
  5. Finalize
    • Incorporate agreed changes after each review
    • Finalize the Content
  6. Publish
    • Integrate the Documentation with the Product or Application
    • Send for final publishing or distribution

Mapping Documentation Development Life Cycle with SDLC

Mapping the Documentation Development Life Cycle (DDLC) with the Software Development Life Cycle (SDLC) isn’t as straightforward as it seems. Some of the reasons are:

  1. Documentation starts quite late in the SDLC: Most often, the last few to get on board a project are the documentation people. Even if they aren’t, the requirement understanding stage for technical writers is extended till the time they get to read a formal requirement specification document or see a prototype. However, it doesn’t happen like that always as sometimes technical writers get to document the design specifications too.
    Image depicting the mapping of stages in SDLC and DDLC
  2. Documentation can’t finish as soon as the Software Development: It is only when the entire software application is developed that the documentation can be given its final shape. Even after all the content in created, there are activities such as language and SME reviews, creating index entries, generating and testing final outputs. All this may take some time until we can announce the completion.
  3. Trivial Changes in the Application may call for Critical Documentation Updates: Small changes such as change in UI resulting in relocation of a button or field, modification in input type on a form, reorganization or reordering on menu may account for an unexpected volume of change across the documentation. It might also require recapturing and replacing numerous screenshots.

With the above factors, the DDLC may not have all its stages completely go hand-in-hand with the SDLC stages. The Requirement Understanding stage of DDLC goes on till the commencement of Construction or Development phase of SDLC. Typically, there would be a lag in Documentation Finish dates and the DDLC would extend the duration of SDLC, too.

By Documentation Development Life Cycle, Documentation Process, Technical Writing , , , , , , , , , , , , , 0 Comments
Read more...
28 Jun

Editing versus Writing

All editors are writers but all writers aren’t editors.

I am quite sure most editors will agree with what I said above. Editing is different from writing and it is much more than proof-reading or reviewing. Those who don’t agree with that opinion, may be actually editing the content under the garb of reviewing and it’s time they start calling themselves Editors. With time, experience and bigger responsibilities, writers are poised to assume the role of an editor. It begins with prolonged exposure to a particular genre of writing, subject matter and the writing style followed. Obviously, when you know your content’s context in and out, you become an authority and can visualize the result of the smallest variations in tone and verbiage. With that, comes the attitude required to become an editor. You start looking at “drafts” and start making “edits” to make the copies read better and explain everything precisely and correctly. You begin to identify and remove the excesses. You look at documents from readers’ perspectives. You are the biggest critic.

Let’s try to answer this – How do you plan your editing?
I think you have to be pretty sure about the expected outcome. You try and match the content drafts with your visualization, make edits, rephrase, paraphrase, reorganize to get an edited version. An editor essentially intends to ensure the following:

  • Correctness of information
  • Accuracy of language
  • Logical flow of information
  • Ability to grab and sustain readers’ attention
  • Conciseness of content
  • Adherence to style guidelines

A point of caution for wannabe editors is that you should respect a writer’s style of writing and expression if it doesn’t come in the way of delivering the right quality. All of us know that we can say one thing in so many ways. However, some editors may want to stick only to their style of writing. This can hamper creativity and leave the writers with little motivation to do something new.

On the other hand, writers need to study the edits, make notes, ask questions, and prepare a personal review checklist. Using the checklist would help reduce the number of editorial changes that writers see in their future drafts.

Editing is also Mentoring
Editing is at best a feedback mechanism for writers. It tells them how to put it better and make it pleasure-to-read. When editors explain their edits either by entering descriptive comments within documents or explaining verbally while being respectful, they are bound to influence the writers positively and they are likelier to see rewarding results soon.translation english to french

By Business Writing, Content Writing, Creative Writing, Documentation Process, Technical Communication, Technical Writing , , , , , 0 Comments
Read more...