In many development organizations, software developers rely on technical documents to communicate and gain consensus on important development

Transcription

1 In many development organizations, software developers rely on technical documents to communicate and gain consensus on important development artifacts. Current document review processes not only make review tedious, but they introduce limitations that actually make it harder to gather and reconcile review feedback from the extended team! Collaborator helps minimize these limitations by allowing multiple reviewers to review the always-current document version at the same time and eliminates the time-consuming comment reconciliation step imposed by Microsoft Word and PDF document formats.

2 Introduction In many development organizations, software developers rely on technical documents to communicate and gain consensus on important development artifacts, such as requirements, specifications, test and validation plans, and customer facing materials. These technical documents are not only critical to project success, but also to the customer validation of product requirements. To ensure that these documents are as accurate as possible, they are shared regularly between project stakeholders product managers and owners, engineers, project managers, technical and documentation team members, marketing staff, and support and QA professionals who edit, annotate and distribute document versions to each other for feedback. Making these documents available to colleagues and requesting their feedback is an important and necessary step in the software development process. Technical artifact review helps secure consensus earlier in the development cycle, identify potentially disruptive issues, and ensure that the full team understands what they are building. Why Peer Review of Documents is Critical Anyone who works in development can tell you that all sorts of development-related information is thoughtfully laid out in documents! From requirements to test cases to customer acceptance criteria, at least a few documents will be changed during the course of the development phase. It happens all the time. Customer needs change, market landscapes evolve, and trade-off decisions often interplay with important delivery dates. When these changes occur, it becomes even more important for stakeholders to review all related technical documents so they can understand the scope and ramifications of every change. Whether you use waterfall or more Agile methodologies, technical documents drive development effort and shape the final result. So reviewing these documents early and often throughout the coding phase is critical to aligning deliverables and releasing valuable working software in the most expedient manner possible. 2

3 Popular Document Review Processes Different organizations have varying degrees of discipline around peer document review. Some employ high-ceremony inspection meetings, others use document-authoring tool features for commenting and annotating documents. There are only a few methods that companies can use to share and solicit technical document feedback: Schedule formal inspection meetings Formal review meetings can be tedious and time consuming. Participants need to review materials prior to the meeting in order to contribute meaningful feedback. The amount of paper consumed in preparation for these meetings is environmentally unfriendly and their long duration makes meeting participants grumpy. Use a document management system Document management systems enable an easy and efficient way to collect, store and retrieve enterprise documents so that the most recent version is always readily available. With the exception of some larger vendors, most document management systems require documents to be authored in other tools, such as Microsoft Word, and then checked into the system. Users of document management systems complain about several significant process issues related to document review: Only one person can review the document at a time, which forces a serial review process The new review cannot begin until the prior review is complete Serial review lengthens the review process Only users of the system (those with a license) can review documents within the document management system. Reviews that require feedback from the extended team (those without a license) need to be distributed via , often as Microsoft Word documents or PDFs. 3

4 In many organizations, only the writers have access to the document management system. This can work well for peer reviews within the documentation team or within the department, but in cases where crossfunctional review is required (i.e., from developers, testers, product owners, etc.) this solution does not scale, because targeted reviewers won t have access to the tool. Create documents and related artifacts in Microsoft Word Many teams create their technical documents in Microsoft Word and use to distribute them to team members. Because Microsoft Office is so prevalent in businesses, Microsoft Word is installed on most office PCs, presenting an easy and expedient way to develop and edit important technical documents. Significant issues arise, however, as the size of the distribution pool increases. The pain users experience from reconciling hundreds of comments from multiple document copies increases exponentially as more edited documents clutter one s inbox. When authors the document to their colleagues for review: They need to remember to append the file to the Reviewers can t see each other s comments s cross, causing confusing overlapping threads Authors have to assess and merge each reviewer s feedback by going through each marked-up document The core issue here is that Microsoft Word was built as a word processing tool, not a document review tool! Google Docs As a means to avoid the limitations of document management systems and Microsoft Word-laden trails, many businesses are turning to Google Docs. Google Docs allows users to review and edit single documents collaboratively, at their convenience, using a browser. Document review is easy since reviewers can still use a Word paradigm and make 4

5 edits directly in the actual document. Although Google Docs solves the collaboration issue, it introduces risk: Google documents are stored online, outside of the corporate firewall. Sensitive information can be exposed which presents privacy, compliance, and security issues. Google Docs lacks both a structured workflow and an audit trail. There is no queue of work and no easy way to track who made what edits without perusing them individually. A further fly in the ointment is that, in the cases outlined above, metrics are not collected, there is no automated issue tracking or sign-off by key stakeholders, and there is a complete absence of any meaningful interaction among the reviewers unless they all gather in a review meeting (which developers and their extended team hate.) Clearly, all these processes are flawed. Why We Need a Better Tool to Review Therein lies the dilemma. In many development organizations, team members rely on Microsoft Word as both a document authoring tool and a review tool. Their challenge is this: Word was designed as a document authoring tool; it lacks core features that support document review. Because the document editing process is not centrally managed within Word, document authors need to navigate through piles of printed documents overrun by tiny comment boxes (or worse threads) in order to reconcile volumes of review feedback. This process is not only confusing in larger teams, but it can lead to pandemonium especially when critical feedback is overlooked, contradicted, or even ignored. Collaborator offers a better way to review technical documents. Purpose-built for document review, Collaborator simplifies the review process, eliminates lengthy trails, and esures compliance with electronic signatures. Let s take a closer look at how Collaborator accomplishes these goals. 5

6 The Challenges with Current Document Review Process Reviewing Documents using Standard Document Review Processes Reviewers may edit outdated document versions Reviewers can t see each other s comments (unless they check in/out doc and modify only one, centrally stored doc), and authors can t see all the comments in one place s cross, causing overlapping threads and confusion Reviewing Documents using Collaborator Documents are centrally managed. All reviewers see the exact same, always current document Reviewers use threaded contextual chats and can see each other s comments in real-time There are no s to cross. All threads are maintained in one place Review meetings that gather the team together are challenging to schedule Comments are deleted and lost Metrics are limited or absent Teams can review documents synchronously or asynchronously. Meetings are not required. Comments are permanently logged. Defects are tracked through resolution Metrics are gathered automatically Lacks inherent document sign-off Enables electronic signatures for key stakeholder document sign-off Documents in can be accidentally forwarded to the wrong party Documents can be downloaded and forwarded in , but never accidentally Collaborator makes the process of document review easier and faster and ensures that all comments are preserved in one location. Meeting regulatory and compliance mandates just got easier with Collaborator s unique document review and electronic signature capabilities. 6

7 Collaborator: Document Review Will Never Be the Same Collaborator builds on proven code review capabilities to help teams apply tool-assisted peer review techniques to the review of documentoriented development artifacts including: Requirements Design documents Project specifications Verification plans Marketing and other customer facing collateral Technical documentation Now, the leading-edge techniques that software developers use to perform code reviews are available to members of the broader project development team. Based on SmartBear s highly-acclaimed collaborative code review techniques that eliminated much of the tedium involved in peer code reviews, Collaborator give teams the tools they need to do reviews in the most efficient way possible. Reviewers can: Comment on the same, centrally-managed, always-current version Use threaded contextual chats and view other s comments in realtime Review comments easily since comments are anchored to text and maintain their context even when information is added, deleted or moved Find, flag and track defects through resolution Eliminate crossed s and maintain comment threads in one place Review artifacts simultaneously or asynchronously, by bringing distributed teams into the review process without meetings 7

8 Extended team members can review technical documents in the same tool that developers use to review code! Document review will never be the same! 8

9 About SmartBear Software More than one million developers, testers and operations professionals use SmartBear tools to ensure the quality and performance of their desktop, mobile, Web and cloud-based applications. SmartBear products are easy to use and deploy, are affordable and available for trial at the website. Learn more about SmartBear, the company s awardwinning tools or join the active user community at on Facebook or follow us on and Google+. SmartBear Software, Inc. 100 Cummings Center, Suite 234N Beverly, MA by SmartBear Software, Inc. Specifications subject to change. SB-DCBT WEB