I recently started a discussion on Overture, a website for the Symphony community, asking for ideas and suggestions. There were many great ideas and one that was expected: improved documentation. I was asked early on to become part of the Overture Team, individuals to moderate and further community desires.
I’m not a technical writer by trade, and I’m a self proclaimed web designer, but this is a realm that I felt like dabbling in and learning about. I decided I would create the user guide for Symphony.
I feel that I am a good candidate for this project because my background is diverse. All too often, documentation is written by those that don’t understand the end-user. Although it may be clear to them, their technical writing lacks the ability to be understood by more than one audience. It fails to deliver to those that are unfamiliar with the technology.
I have learned quite a bit during the preliminary phase of putting together the user guide. Audience considerations are paramount and crucial during this phase. I took into account two audiences as I put together the structure of the user guide.
Writing a technical manual for two audiences is a difficult challenge. Especially when the audiences are very different. The manual is comprised of roughly six chapters. It covers all aspects for those unfamiliar with both Symphony and XSLT. This will fulfill my first audience requirement.
After speaking with Allen Chang, he emphasized the importance of illustrating the proper workflow in Symphony as intended by the developers. I agree on this sentiment and have taken it one step further. I have created the infamous “Getting Started” chapter so that it is focused more towards individuals with a XSLT background. It is the chapter that allows those familiar with the technology to get a “quick start” with the Symphony interface, and additionally, understand the workflow process in Symphony. I believe this fulfills my second audience’s needs.
Technical writing does not have to alienate the user. I believe I have taken into account the two most prominent prominent users and made accommodations that don’t step on one another’s toes.