Lessons learned from ICT Architecture
Just like technical writers, ICT Architects face the challenge to describe platforms, systems and solutions from a business point of view. But where there seems to lack a standard for technical writers, ICT Architects have the luxury of having frameworks like TOGAF and notation methods like Archimate to help them do their work.
Function-oriented versus user-oriented documentation
No doubt that there are still technical writers out there who don't agree with me, but to me it is clear that a user-oriented approach to documentation is the way to go. So if I am talking about making documentation from a business point of view, I am in fact talking about creating a documentation solution that fits the user's needs. Whether or not this is a printed book, a website, embedded on-line help or a combination of all these, doesn't make a difference, as long as the presentation form is chosen from a user's point of view.
Where to start?
We all know the feeling when we accept a new project as a technical writer: Where should we start?
I have always learned that a good starting point for user-oriented documentation is the audience analysis (Wapenaar et al., 1989). This will provide us with more or less detailed information about our audience in terms of age, gender (percentages), religions, regions, languages and education levels. Suffice to say, this might be enough to start writing a flyer or brochure but for a user-oriented documentation solution this is not sufficient. An analysis of user tasks and processes should therefore be required, but is often regarded as too expensive and time consuming.
Processes in ICT Architecture
In the past 1,5 year I have worked as an ICT Architect at the IT Services Department of USG People the Netherlands and made Project Start Architecture Documents for several new ICT solutions. Although they will probably not see the similarity themselves, ICT Architects face a similar challenge as technical writers when it comes to describing a platform, system or application. It is not coincidence that architecture frameworks like TOGAF and DYA made processes an important artefact within the enterprise architecture. In fact the business architecture - centred around goals and processes - might as well be the most important of the four pillars within the TOGAF framework.
What I will do in this series of blogs is use the lessons I have learned as an ICT Architect and translate them to a method that could be used by technical writers. Although I will focus on the first phases of the writing process and compare them with similar steps in defining the Business Architecture, I will also look at the overall architectural framework and see what we can learn from it.
Function-oriented versus user-oriented documentation
No doubt that there are still technical writers out there who don't agree with me, but to me it is clear that a user-oriented approach to documentation is the way to go. So if I am talking about making documentation from a business point of view, I am in fact talking about creating a documentation solution that fits the user's needs. Whether or not this is a printed book, a website, embedded on-line help or a combination of all these, doesn't make a difference, as long as the presentation form is chosen from a user's point of view.
Where to start?
We all know the feeling when we accept a new project as a technical writer: Where should we start?
I have always learned that a good starting point for user-oriented documentation is the audience analysis (Wapenaar et al., 1989). This will provide us with more or less detailed information about our audience in terms of age, gender (percentages), religions, regions, languages and education levels. Suffice to say, this might be enough to start writing a flyer or brochure but for a user-oriented documentation solution this is not sufficient. An analysis of user tasks and processes should therefore be required, but is often regarded as too expensive and time consuming.
Processes in ICT Architecture
In the past 1,5 year I have worked as an ICT Architect at the IT Services Department of USG People the Netherlands and made Project Start Architecture Documents for several new ICT solutions. Although they will probably not see the similarity themselves, ICT Architects face a similar challenge as technical writers when it comes to describing a platform, system or application. It is not coincidence that architecture frameworks like TOGAF and DYA made processes an important artefact within the enterprise architecture. In fact the business architecture - centred around goals and processes - might as well be the most important of the four pillars within the TOGAF framework.
According to TOGAF, Business Architecture is a disciplined approach to realize business models and is meant to serve as a business foundation of the enterprise to enhance accountability and improve decision-making. Business Architecture's value proposition is to increase functional effectiveness by mapping and modelling the business to the organization's business vision and strategic goals.
So how does this help us?What I will do in this series of blogs is use the lessons I have learned as an ICT Architect and translate them to a method that could be used by technical writers. Although I will focus on the first phases of the writing process and compare them with similar steps in defining the Business Architecture, I will also look at the overall architectural framework and see what we can learn from it.
Comments