Category Archives: Training

Our March 2012 Meeting: “Agile Documentation (Hi, Honey, I joined a cult!)”

Meetings, STC NorthBay Blog, Training, Uncategorized

Fundamentals of Agile Development
Mike Ziegenhagen, a technical writer and tech pubs manager in the software business for more than 18 years, has also specialized in documenting virtual worlds. One virtual world you may be familiar with is the one that “relates” (read “force fits”) product specifications to actual products. If you have ever suffered from the disconnect between fantasy specs and real deliverables, you will appreciate how the Agile process keeps a tight rein on development, making sure that each feature works properly before subsequent features are added — all executed in cycles of generally a couple of weeks at a time. The Agile approach embodies the principal of iterative and incremental development: Never get ahead of yourself, and keep it real. While “Agile Documentation” is not yet a topic on Wikipedia, it is not hard to extrapolate from stepwise development to stepwise documentation.

Mike spoke from experience. For the past two years he’s worked with a team of writers in a large enterprise software company that embraced Agile software development from the top management team down. (Without proper buy-in and support at the highest levels, it is hard to realize the benefits of this approach.)

Some Basic Principles
An Agile Manifesto lists four fundamental priorities. Favor . . .

  • Individuals and interactions over Processes and tools
  • Working software over Comprehensive documentation
  • Customer collaboration over Contract management
  • Responding to change over Following a plan

    • There remains value in the functions on the right, but these should never dominate.

    Real reality, not the virtual variety, is key. Unlike the all-to-familiar MS Project approach, where 100-page best-laid plans of mice and men soon go stale, Agile requires daily truth-telling sessions in meat space. Each participant stands and briefly addresses three questions: What have you done since yesterday (in an interval known as a “sprint”), what are you doing today , and are you being blocked from what you have to do? A series of sprints comprises a release for the multiple teams, called a scrum (yes, development can be bruising like rugby). In the sport, a scrum restarts the game after a minor infraction — a fair analogy. In development, a Scrum Master ensures that progress is made at each sprint truth-telling session. At the top of the process is the Product Owner — who is closest to the “first customer” and knows precisely what a potential buyer needs, wants, and is willing to pay for. All other features can come after the basic functionality of the product is rock solid. What a concept!

    And the benefits?

  • Avoid the “spec monster” approach, which creates bloatware or (worse yet!) phantomware.
  • Avoid turning the prototype into a product (seen that fantasy before?).
  • Meet changing needs and markets easily, simply by adding or removing iterations (you can always catch up later if you need to).
  • Address bugs early and often, preventing unplanned delays in product releases.

    • Agile Documentation
    Until someone writes the Agile Documentation page on Wikipedia, here are the principles Mike has arrived at from his experience as a writer involved in the Agile process:

  • Don’t sweat providing documentation for discoverable tasks. (Click OK already!)
  • It is virtuous to keep things simple, but only if you provide enough information for the user to accomplish a task.
  • Provide simple documentation for complex tasks (keeping in mind the principle above).
  • Don’t make documentation more than it deserves to be. Documentation is part of the process of users doing their work; it is not the process (communicate rather than “document”).
  • Write the documentation you would like to read. (What a concept!)
  • Follow the principle of Occam’s razor: Keep things as simple as possible, but no simpler (see above).
  • Build documents from the center outward, as time allows. Use the software, take notes, flesh it out. Do not write the outline and fill it in with content! (cf. “fantasy specs” above)

    • But Wait, There’s More!

    This should be enough to get you interested and motivated to learn more about Agile. And what better resource for that than the excellent slides you may have missed if you were not at our meeting. Many who attended will have some thoughtful insights to take back to the workplace.

    So dig a bit and see what Agile could do for you!

    Introduction to DITA Workshop in Cupertino

    STC NorthBay Blog, Training,

    On August 7, 2010 at DeAnza College in Cupertino, the STC Silicon Valley chapter will have an “Introduction to DITA Workshop.” Some of the topics covered will be DITA concepts, tasks, references, DITA maps, tools and technologies (DITA Open Toolkit, XML Mind). There will also be hands-on examples so students will work on pieces they can include in their portfolios.

    Register before July 25, 2010 and pay only $60 for STC Members and Full-Time Students and $75 for Non-members. Register after July 25, 2010 and the fee goes up to $75 for STC Members and Full-Time Students and $100 for Non-members.

    To register visit http://stcsv.wufoo.com/forms/intro-to-dita-workshop/

    APIs and SDKs: Breaking into and Succeeding in a Specialty Market

    STC NorthBay Blog, Training, , ,

    Seminar presented by API/SDK documentation expert Ed Marshall, Marshall Documentation Consulting in Boston.

    Cost: $195 per person (includes breakfast and lunch)
    When: Saturday, August 28, 2010, 8:30 a.m.–5:00 p.m.
    Where: Best Western Pony Soldier Inn, 9901 NE Sandy Blvd., Portland, OR

    Since the early 1990s, the demand for application programming interface (API) and software development kit (SDK) documentation for developers has grown rapidly and shows no signs of declining. At the same time, there’s a shortage of writers in this niche. They enjoy a steady income, higher hourly rates, and often the luxury of telecommuting.

    Contrary to some perceptions, API/SDK writers are typically not computer programmers. They’re technical writers who are detail oriented, who know how to glean information for documentation by reading developers’ code and communicating well with developers. Although having familiarity with one or more programming languages is important, technical writers can leverage skills they already have to add value to API/SDK documentation, such as the ability to organize information, recognizing where important gaps in the content exist, and providing consistency in content and use of terms.

    How do you enter and succeed in this market? Join Ed Marshall, a nationally recognized expert in API/SDK writing, for an introduction to this world of writing documentation for software developers on Saturday, August 28. During this all-day, hands-on workshop, you will learn:

    • What APIs and SDKs are and the similarities and differences between them.
    • Who uses APIs and SDKs and why.
    • The benefits and drawbacks of API/SDK writing.
    • How to gather information, primarily by reading the software code. For example, which files do you read? Which programming keywords are important?
    • What information you can get from the source code and what to look for. What information you can’t get from reading the source code.
    • Hands-on exercises using Doxygen and Javadoc to generate typical online documentation from a set of C and Java source code files.
    • The skills you need to succeed, including common programming concepts, software applications used for creating these documents, and tips for adding value based on your technical knowledge.
    • Where to find training.

    Ed will also show examples of typical API/SDK documents and demonstrate the software tools used to generate documentation from the developers’ source code. He will allocate ample time for participants to practice with these tools. Laptops are needed to complete the hands-on exercises. All the software needed will be provided by the instructor for installing on your laptop.

    About the Instructor

    Ed Marshall is an independent technical writing consultant and sole proprietor of Marshall Documentation Consulting, with more than 22 years of experience. He specializes in APIs/SDKs (application programming interfaces/software development kits), Web services products, and other types of documentation aimed at developers. Throughout his career, Ed has developed expertise in using tools to “let the computer do the work,” such as advanced tools for editing files, comparing files, and searching and replacing text in files.

    Ed is a popular speaker at a variety of professional development conferences, locally and nationwide. His previous appearances include events sponsored by the Society for Technical Communication (STC), WritersUA, and DocTrain.

    For more details and to register, see www.tabbycatco.coml.