Writing skills for the IT architect are the ability to effectively communicate information in written text form. They are used in a variety of tasks, such as writing documents, email correspondence or e.g. when posting a report in a blog. Most of what architects deliver as written text falls into one of the following categories:

• Description of systems, such as documenting architectural artifacts or requirements
• Correspondence with collaborators, stakeholders, subject matter experts or customers
• Preparation of a report, such as an assessment or a summary of an investigation

The importance of writing skills becomes most apparent, not when they are present, but when they are missing. In the best case, inadequate writing could result in losing the reader’s interest or the author’s credibility. However, in the worst case, information could be misunderstood and result in poor decision making with severe consequences for a project or organization.

The basics of writing for an architect are generally similar to those of professional writers. Clarity and simplicity are essential as well as good structure and correct grammar and spelling. Further, writing should be specifically tailored to the reading audience. E.g. information prepared for business stakeholders typically requires less detail than information for engineers. Having a good foundation in writing is important, since information can easily be lost or ignored if it is not articulated well. Any written document reflects on the credibility of its author. It is therefore in the best interest of the architect to be proficient in this capability.

Especially relevant to the IT architect profession is the ability to describe information correctly and accurately. It starts with precise wording, but also includes proper use of terminology. Using standard technology and business terminology will ensure that all readers have the same understanding of the described content. The goal is to avoid ambiguity as much as possible, since it can lead to misunderstandings that can take a long time to resolve or even cause poor decision making. Language used in a document or email is often repeated in follow-up communication, so it is always best to pay attention to accurate wording from the beginning.

The most common use of written text is for the description of systems, specifications or other architectural artifacts. E.g. it is very common for an architect to write a document that outlines a new system in form of requirements, components, business rules or other artifacts. While diagrams are often the core of the document, it is the text that provides the framework and walks the reader through the different views to create a holistic picture of the system. There are many common practices on what formats to use for documents and specifications. Most mature organizations have guidelines and templates that are expected to be followed in order to standardize processes and representation of information.

Another common area of writing by architects is correspondence via email or communication portals. The purpose of the correspondence is usually related to gathering or distribution of information, but can also be more general in nature. E.g. it is common in practice to address critical follow-up questions to a meeting or document review by email. To be successful, it is important to be familiar with business correspondence practices, such as greeting and thanking the recipient. There are many casual correspondence practices that are being frowned upon in a professional environment, such as the use of smileys, slang, etc. It is best to avoid these completely, since they can result in reluctance to cooperate by the other party.

On a more senior level, an architect may be asked to write a report or paper about a new technology or the feasibility of an architecture proposal. An additional skill is required for this type of writing task, which is the ability to advocate an opinion and convince the user of a perspective or proposal.

There are many other areas where writing skills are important. E.g. architects may be needed to help with critical parts of product documentation or they can be authors of papers or blogs.

Much of the information capturing and sharing in organizations is based on written text. With good writing skills, the IT architect contributes to efficient distribution of information, which is key to the success of a company. Architects are usually the owners of especially complex and valuable information. The ability to express this information in text form is therefore a frequently used tool in practice.

There are many established writing practices, which are often automatically acquired over time. The most common ones are as follows:

General Writing

• Description of the context for the written information (E.g. which product or project is it for?)
• Use of spell checker
• Use of short sentences in active form
• Use of paragraphs, bullets and font variations to structure text
• Marking information as confidential where applicable

Document Writing

• Listing of authors and revision history
• Table of content for larger documents
• Executive summary for larger documents
• Use the “shall” form for requirements or use user stories
• Use of a glossary, especially for acronyms
• Listing of references and citations
• Put detailed information into an appendix
• Use of an automatic change tracker

Correspondence

• Use of common courtesy, such as Hello, Thank you, Sincerely, and Best regards
• Avoid using shortcuts, emoticons, jargon, slang, and all letter capitalization
• Politeness and simplicity in international correspondence and consideration of cultural aspects
• Well chosen descriptive subject lines in email
• Summarize required actions at the end or beginning of email
• Re-read text before sending

Clarity and Accuracy

The ability to express information clearly with organized thought. Use of an overall structure and flow that is easy to follow. Correct use of language, grammar and spelling. Elimination of ambiguity and proper use of technology and business terminology.

Business Correspondence

Effective communication with the purpose of information exchange or coordination of activities. Includes proper etiquette and the ability to drive progress through effective correspondence.

Text and Document Formatting

Ability to use text formatting to structure text and make it more readable. The ability to format documents according to best practices

• Architecture Description
  – An architecture is usually described in a document, which has a framework of written text. Writing skills help create a document that is easy to follow.
• Requirements Modeling
  – Requirements are usually captured in some form of written text. Writing Skills will make the requirements more clear and easy to follow.
• Presentation Skills
  – Creating presentation material with elements of written text can greatly benefit from Writing Skills.

Basics of professional writing: https://en.wikipedia.org/wiki/Professional_writing

Purdue University Online Writing Lab: https://owl.english.purdue.edu/owl/

Email correspondence etiquette: http://www.inc.com/guides/2010/06/email-etiquette.html

Wikipedia Manual of Text Formatting: https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Text_formatting

Sven Jug

Sven is a Senior Engineering Manager at KLA-Tencor, a global semi-conductor company. He is responsible for managing projects, people and architectural solutions for data management and analysis software products.

While in different roles, including architect, program manager, developer, researcher and people manager, Sven has continuously been practicing the architecture profession in a full or part time capacity over the years. One of his key responsibilities at KLA-Tencor is developing and integrating solutions across divisional, regional and international boundaries.

Sven lives in Austin, Texas and has over 17 years of experience in software solution development. He holds a master’s degree in Mathematics from the Humboldt University of Berlin, Germany.