http://tc.eserver.org/dir/Agile/Documentation A listing of the most recently indexed works about Agile and Documentation in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Agile/Documentation http://tc.eserver.org/35803.html http://tc.eserver.org/35803.html Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment. http://tc.eserver.org/35421.html http://tc.eserver.org/35421.html It's a simple fact of life. Developing products in today's world requires shorter cycles, sensitivity to customer needs, and a focus on deliverables that breaks the old waterfall development paradigm. More and more there is a need for teams to focus on the entire development process and deliver precisely what customers need with little or no fluff. As products move towards the user-centric model of product development the push is for more intuitive interfaces with little need for documentation -- or does it really? http://tc.eserver.org/35192.html http://tc.eserver.org/35192.html The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well. http://tc.eserver.org/35040.html http://tc.eserver.org/35040.html uScrum (uncertainty Scrum) is an agile process developed by a small team at Altitude Software to manage the process of writing user documentation. uScrum manages uncertainty and the unknown, allowing writers to quickly react to changing conditions. uScrum uses orders of ignorance to understand the difficulty of tasks, allowing the team to effectively prioritize regular work together with difficult creative work. http://tc.eserver.org/32352.html http://tc.eserver.org/32352.html Some agile environments move so fast, you have to triage what you document because there’s no time to document everything. http://tc.eserver.org/32156.html http://tc.eserver.org/32156.html What’s it like doing documentation as part of an Agile software development team? Why is it a better way of working? I mull this over these and other questions with Graham Campbell. http://tc.eserver.org/31163.html http://tc.eserver.org/31163.html Documentation teams need a fast and effective review process to move forward on their projects and deliver quality, timely content. Reviewers, may they be SMEs (Subject Matter Experts) or key organization authorities, are usually extremely busy and have limited time (or interest) to review documentation. Interesting dilemma, no? http://tc.eserver.org/30762.html http://tc.eserver.org/30762.html Storytelling can make documentation more exciting for both writers and readers. Stories provide context and people tend to remember them. More all-∆around fun when stories are tests. http://tc.eserver.org/30729.html http://tc.eserver.org/30729.html Documentation is an important part of agile software development projects, but unlike traditionalists who often see documentation as a risk reduction strategy, agilists typically see documentation as a strategy which increases overall project risk and therefore strive to be as efficient as possible when it comes to documentation. Agilists write documentation when that's the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation. This article summarizes common "best practices" which agilists have adopted with respect to documentation. http://tc.eserver.org/28121.html http://tc.eserver.org/28121.html A Test Map is a list of unit tests associated with a specific function/method under test. It helps you see how that specific function/method is being exercised via unit tests. http://tc.eserver.org/27609.html http://tc.eserver.org/27609.html When it comes to getting work done, replace written documentation with more efficient forms of communication. To guide future work, create documents at the end of the project, when everything is complete, well understood, and easy to document. http://tc.eserver.org/27608.html http://tc.eserver.org/27608.html In agile software development you want to travel as light as possible, and the easiest way to do that is to choose the best artifact to record information. I use the term 'artifact' to refer to any model, document, source code, plan, and so on created during a software development project. Furthermore, you want to record information as few times as possible, ideally only once. For example, if you describe a business rule in a use case, then describe it in detail in a business rule specification, then implement it in code, you have three versions of the same business rule to maintain. It would be far better to record the business rule once, ideally as human-readable but implementable code, and then reference it from any other artifact as appropriate. http://tc.eserver.org/27601.html http://tc.eserver.org/27601.html Why do we bother with models or documentation? They don't execute, and our customers pay us for working code, not pretty pictures. We bother with models to communicate. The idea is that a graphical object model can show how objects fit together more clearly than looking at the source, an interaction diagram can show a collaboration better than figuring out the call path from several class definitions. But so often the design documentation fails in this, and leaves me puzzled on my sofa. http://tc.eserver.org/27603.html http://tc.eserver.org/27603.html Discusses the life cycle of Story Cards, what they should be, how to use them and what to watch out for. http://tc.eserver.org/27604.html http://tc.eserver.org/27604.html The basic idea is that very little of the documentation which gets created during software development actually gets read by the actual target audience. This article explains the problem and presents advice for addressing it. http://tc.eserver.org/27589.html http://tc.eserver.org/27589.html In Agile Documentation, Rüping gets to the heart of the documentation dilemma, offering a two-word solution: minimum necessary. http://tc.eserver.org/27590.html http://tc.eserver.org/27590.html With limited staff, a rapidly changing IT environment, and increasing complexity, my own inflexible documentation practices had to be updated to reflect more dynamic environments. http://tc.eserver.org/27591.html http://tc.eserver.org/27591.html Recently, Agile Software Processes have been discussed as flexible and light-weight alternatives to established Software Engineering approaches, in order to overcome the obstacles created by the cost of producing and maintaining documents on higher abstraction levels. Depending on requirements and needs on the documents itself, Agile Documentation becomes a key issue and brings up questions on how to create, maintain and distribute documents among the team members without creating unnecessary or unjustifiable cost. This paper describes a technique allowing to produce documentation automatically, by conducting analysis on the series of development steps taken during project planning and enactment. http://tc.eserver.org/27588.html http://tc.eserver.org/27588.html When I initially started work on Agile Modeling (AM) I wanted to focus solely on principles and practices for effective modeling but quickly discovered that this scope was not sufficient, that I also needed to consider the issue of how to be effective at the creation and maintenance of documentation too. Some agile models will 'evolve' into official system documentation, although the vast majority will not, and therefore it is relevant to discuss how to be agile doing so. http://tc.eserver.org/27572.html http://tc.eserver.org/27572.html What quicker way can there be to find out if something is teachable than to write up task-oriented documentation? And as things are built or changed, the documentation is updated. I often update the documentation before the code! http://tc.eserver.org/27586.html http://tc.eserver.org/27586.html Extreme Programming (or XP) is a popular software development process that encourages a return to the days of little or no documentation, Design After First Testing, and Constant Refactoring After Programming. Despite its popularity, not everyone thinks XP is a good idea. http://tc.eserver.org/27587.html http://tc.eserver.org/27587.html This is a description of a simple software-internals documentation format and process. It is derived from the Unified Software Development Process, simplified towards eXtreme Programming compatibility, and arranged for realisation in a plain text file. http://tc.eserver.org/27585.html http://tc.eserver.org/27585.html A broader awareness of how changes can impact other things, including schedule commitments and work outside of the immediate area of change, is beneficial in terms of assessing trade-offs and benefits. http://tc.eserver.org/19666.html http://tc.eserver.org/19666.html A revolution is under way in software development, revolving around agile methodologies that allow more room for design changes based on input from customers during development. One popular agile methodology is eXtreme Programming (XP).