Saturday, June 27, 2015

A primer on Agile software development

Until the introduction of Agile, the standard software development life cycle (SDLC) was a Waterfall approach, where each stage of the SDLC had to be completed before the next one could begin. Requirements had to be gathered in great detail. Design would only begin once the requirements were completed. Development began once the design was complete, and testing didn’t start until development was done. This method left those people with a vested interest in the project (stakeholders) wondering what was taking so long. There was nothing tangible to show that any progress had been made.

The basis of working Agile is the Agile manifesto from the founders of Agile: We are uncovering better ways of developing software by doing it and helping others do it. Through this work we have come to value:
  • Individuals and interactions over Processes and tools
  • Working software over Comprehensive documentation
  • Customer collaboration over Contract negotiation
  • Responding to change over Following a plan

That is, while there is value in the items on the right, we value the items on the left more.

Let’s just establish right now that “Comprehensive documentation” is referring to planning and tracking documents, not user assistance. The point is that Agile values a product that people can use over writing about what that product is going to be or should be.

The introduction of Agile was a new way of thinking. Instead of detailed requirements, there were user stories. Each story identifies the person associated with the requirement, what the requirement is, and what this functionality will help the person to achieve. For example, purchasing agents need the ability to enter order information online so that it can be sent directly to outside vendors. This may be considered a very large user story, which is referred to as an epic. This epic can be broken into smaller user stories, which will make it easier to provide estimates and will enable work for smaller user stories to be associated with different iterations.

Some examples of smaller user stories that could be associated with this epic would be:
  • Purchasing agents must have the ability to enter a vendor’s name, address and telephone number and associate it with a vendor number so that the purchasing agent can use the vendor number when placing future orders.
  • Purchasing agents must have the ability to select from a list of standard products when placing an order so that consistent terminology is used and inventory can be tracked more effectively.
Using these user stories, the Agile team assesses and estimates the complexity of the software design and development associated with them. These estimates are in the form of points. The larger the number of points associated with a user story, the more complicated and time-consuming the design and development is believed to be.

Unlike a waterfall SDLC, which is a linear approach, Agile is iterative. Before each iteration, which is called a sprint, the Agile team agrees on the tasks they are going to complete during the sprint. The total points estimated for the completed tasks is referred to as the velocity. The planning for the next sprint should change based on what happened in previous sprints. For example, if the velocity for the previous sprint was 50 and the team had estimated they could complete 75, the team may select less user stories to complete and aim for 50 the next time. After a few sprints, the team and management can get a good picture of the velocity and predicted end date of the project, given the current scope and resources. That’s one of the benefits of Agile. The information learned during one iteration can be applied to the next iteration instead of identifying lessons learned at the end of a project so that they cannot be used until the next project.

A lot more can be said about Agile and Agile tools, but we’re hoping to just establish the background for you to understand the following series of stories. Debbie Kerr, Ursula McCloy and Fei Min Lorente are three people who work in Agile environments. This introduction will be followed by articles where each of them describe how Agile has been implemented at their work places. Although Agile provides a new paradigm for software development, it favours people over processes, making an Agile experience in one company vastly different from the next. 




Sunday, June 14, 2015

SPFE: Synthesis, Presentation, Formatting, and Encoding

By Fei Min Lorente

Mark Baker was generous enough to deliver another seminar to the Southwestern Ontario Chapter. He explained why and how to use SPFE (pronounced “spiffy”), which is a fascinating architecture for anyone—professional writers and casual contributors alike—to create individual pages and let the architecture take care of incorporating them into publications. It removes the barrier of a specialized markup language or specialized interface that someone has to learn before putting information directly into a structured and self-organizing format. It’s designed for documentation that will be published on the web.

Why you would want to do this is explained in the other seminars that Mark has presented to us: Every Page is Page One and Information Architecture—Bottom Up*! To summarize, people usually find information by searching first, which means that they won’t necessarily start reading on any particular page (hence, every page is page one). This means that the top-down organization of information is mostly irrelevant. In other words, if you try to organize information in the order you think people are going to read, you’re setting yourself up for failure. Wikipedia is Mark’s favourite example of how information should be organized for maximum usability. Each page is a topic, and all the information on a page is at the same “level”—it doesn’t mix generalities with details. For details, you can click on one of the many links that will explain what you need to know.

For more reasons to look at SPFE more carefully, imagine training your SMEs to do structured authoring, without them having to learn about the publishing system or content management. To them, it will look like they are filling out a form, with field names they can understand so that they know what to write. They will have to think about the rhetorical structure and the annotation of their subjects, but they already know this information, and are simply learning to express it formally. SPFE guides their input while saving you the time of writing everything from scratch. It enables distributed authoring, which means a shorter time to publishing the most up-to-date information.

After all, customers expect accurate and up-to-date information whenever they search for it. This means that the publishing cycle has to be instantaneous. It’s one thing to collect up-to-date information and publish it at the press of a button, it’s another thing to create and maintain all the links, especially if you’re publishing a subset of the documentation. SPFE uses the semantics of the information to create links. For example, if the SME identifies something as a feature, SPFE will go looking for another page about that feature, and automatically link to it. If there isn’t an existing page about that feature, SPFE will point out that you’ve got a gap in your documentation. You can choose whether to add that information or ignore SPFE’s advice at that point.

To help guide your SMEs with their information input, you need to customize the “form” to reflect their area of technical expertise. You might do this now with a customized DTD or schema, or by using a subset of DITA, but it would be an awkward way to do it. If you have ever implemented such a structure, you know that this isn’t an activity that you’d want to do often. SPFE, on the other hand, makes this structural customization easy so that the SMEs don’t have to learn a complex and foreign markup language, while you can harness the power of structured content with metadata. You can reuse SPFE’s existing structures, which are composed of elements, leave out the ones you don’t need, change the ones you want to customize and add new ones. You can also reuse and customize the scripts that validate and automate the linked output.

Yes, there are scripts involved. Working with SPFE is not for the faint of technical heart, but if you know a good programmer, this is the most flexible documentation system available (i.e., it’s not tied to any particular tool). Mark is using oXygen as his editor, Python to manage the build process, XSLT to process the markup, and CSS to format the output for the web; however, since everything is text-based, you can choose any tool or scripting language, as long as you follow SPFE’s general architectural design and design principles. SPFE is open-source, so you are free to use it as you need.

The concepts behind SPFE are well-reasoned, but considering it took Mark three presentations to lead us to this open architecture, it’s hard to condense the information to one blog article. If I’ve piqued your interest, I recommend taking a look at the SPFE pages on the web, starting with http://spfe.info/. Oh, sorry, I’m supposed to let you choose your own first page.

*For a more complete article about Mark’s Information Architecture—Bottom Up, see Sarah Maddox’s write up.