TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Great assignment! This can be very helpful to your potential customers and perhaps even to your development team.
You actually have two projects here: the architecture description or concept of operations, and the deployment (implementation) processes.
Somewhere in your organization there is a chief architect or lead developer who has architecture diagrams (but maybe not easily exportable diagrams, and maybe scrawled on a whiteboard). This person should be your technical source or point you to your technical sources.
For the deployment processes, your source is the project manager who actually supports customer implementations. Do they have a workbook or checklist?
For general background in architecture, you could consult the freely downloadable Software Engineering Body of Knowledge v3 from the IEEE Computer Society at https://www.computer.org/web/swebok/v3
For an idea of all the viewpoints from which IT architectures can be documented, take a look at the free DoDAF specification at http://dodcio.defense.gov/Library/DoD-Architecture-Framework/
There is a standard on contents of life-cycle information (such as architecture descriptions and transition plans), ISO/IEC/IEEE 15289. However, this is aimed at system documentation, not at marketing communication. http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=7109795&newsearch=true&queryText=15289
By the way, there is a new standard on content management systems: http://ieeexplore.ieee.org/search/searchresult.jsp?newsearch=true&queryText=26531
ISO/IEC/IEEE International Standard for Systems and software engineering -- Content management for product life-cycle, user, and service management documentation
Probably your first goal will be to develop the diagram that conveys the salient features of the architecture that your organization wants to convey to your customers. Next, the text that presents the features of the architecture. Then focus on the transition steps or processes.
Best wishes. The best customers are ones that think they understand what they are getting.
-----Original Message-----
From: Helen Mullally [mailto:helen -dot- mullally -at- alfresco -dot- com]
Sent: Wednesday, June 29, 2016 10:56 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Reference Architecture document
Iâve been asked to take on the creation and production of a Reference Architecture document, covering the hardware, software, and processes for a deployment. The document is intended primarily to support the sales process, rather than being a part of the product documentation.
Has anybody got any experience of writing or managing the production of a Reference Architecture document?
Do you have any advice on the typical SMEs to assist with the definition of the architecture and contributing to the content? Did you encounter any pitfalls or conflicts?
Thanks for any advice.
Helen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
