1.

Introduction

The Large Synoptic Survey Telescope (LSST) is an 8.4-m wide-field (3.5-deg) survey telescope. It is currently under construction on the summit of Cerro Pachón in Chile. LSST received its construction authorization from the National Science Foundation in August 2014. The goal of the LSST project is to conduct a wide, deep, fast survey via a three-mirror wide field-of-view optical design, a 3.2-Gpixel camera, and an automated data processing system.

Writing and reviewing documentation for any project is a tedious, time-consuming process. In many engineering environments, documentation is poorly written, or in many cases, is left uncompleted until the end of a contract. From the LSST perspective, this implies that technical writers are inundated with subsystem drawings and vague documentation before the completion of a project, having no clear understanding of the project’s function or the systems connecting to it.

To avoid this, LSST creates the technical documentation in parallel with the design at a very early stage in the design process for faster development and faster information flow. During the current construction phase of the project, LSST is creating all necessary technical documentation, in collaboration with worldwide astronomical agencies and vendors.

Due to the LSST design and integration complexities, effective, simplified, and up-to-date technical documentation is critical to contributing to a safe and efficient work environment. Technical documentation must be readily accessible, easily modified, and understandable for non-English speaking personnel. Moreover, the documentation is essential for all aspects of the project, including assembly and installation procedures, operation and maintenance manuals, checklists as well as training.

With this process, LSST technical documentation and animations are always kept up to date with any in-house or vendor-driven design changes and are readily accessible through the content management system.

2.

Technical documentation for LSST subsystems

LSST creates technical documentation in collaboration with the vendors for the construction, integration, operation, and maintenance of all LSST subsystems.

Definition of “Technical Documentation”:

LSST writes the technical documentation in collaboration with worldwide vendors for all LSST subsystems and support facilities:¹

The software technical documentation for the observatory control system and telescope control system is managed by the software team. The installation manuals and integration procedures are currently incorporated as part of the same software development kits (SDK) and have been available to the vendors and external teams (camera, data management, systems engineering) during their development process.

The technical documentation for operations and maintenance will be provided along with the software packages, at the end of construction, to the assembly integration and verification (AIV) and commissioning teams.

SOLIDWORKS^® Composer is used for optomechanical, pneumatic, cooling, and heating documentation. LSST does not use SOLIDWORKS^® or SOLIDWORKS^® Composer for electrical design. When the LSST project started, SOLIDWORKS^® electrical design capability was not sufficiently matured to fulfill the needs of LSST. The electrical documentation utilized other methods.

3.

Creation and Storage of Technical Documentation

For the creation and storage of technical documentation, LSST uses the following software programs and systems:

The technical documentation is linked to the CMMS. When the CMMS system determines that maintenance is required it references the corresponding procedure.

4.

LSST Technical Writing Process

To start the LSST technical writing process, the technical writer and subsystem manager first produce a project plan showing what technical documentation is required, such as procedures or manuals for assembly, installation, operation, maintenance, or training. Next, they determine which documentation will be provided from the vendor and which documentation LSST needs to provide. They must also determine which language to use, English or Spanish, as well as the priority and available workforce for the technical writer. A subject-matter-expert (SME) provides input. Separate reviewers and approvers, determined by the subsystem manager, are utilized for the final document. The final project is stored in Atlassian confluence.

The master documents of the projects’ assembly are the AIV plans. The technical documentation describes individual processes, which when combined together represent the overall AIV plans.

To start the actual technical writing process, the technical writer gathers information and resource material (SOLIDWORKS^® CAD files, drawings, procedures from vendor, etc.) about the subsystem, which needs to be documented and conducts content gathering meetings with the SME. The SME and/or vendor will provide the technical writer SOLIDWORKS^® 3-D CAD models to create 3-D images with SOLIDWORKS^® Composer. All 3-D images are saved in the product data management system SOLIDWORKS^® PDM professional.

For the review and approval process, the technical writer writes the first draft, sends it to the SME for review, implements their feedback, and creates a second draft, which is then sent to the document reviewers. The feedback from the document reviewers is implemented. A final version is created for approval signature. The final document is published by the technical writer in Atlassian confluence and archived in the LSST storage system DocuShare^® (Fig. 1).

5.

Technical Writing Process Advantages and Results

There are several advantages and significant benefits from our technical writing process:

In the following chapters, we will find a detailed description of the listed advantages and technical writing process.

6.

Automatic Updates if Design Changes

LSST creates the technical documentation in parallel with the design at a very early stage in the design process for faster development and faster information flow. With SOLIDWORKS^® Composer, all 3-D images and animations are created from existing SOLIDWORKS^® models, which are stored on the product data management system, LSST PDM vault.

With the integration of SOLIDWORKS^® Composer, technical documentation can immediately and automatically be updated by accessing the 3-D model through the LSST PDM vault. For example, imagine we just finished describing a 100-page assembly procedure of a component using multiple 3-D model images of the component to explain the assembly sequence step-by-step. Then, for this example, assume the engineering team responsible for the component decides to modify the 3-D model. In the past, a technical writer would be required to edit all images in the preliminary document. This process is very tedious and time-consuming. Without this process, CAD models evolving quickly, before a final design is recognized, makes documentation revisions difficult to edit and track. However, using SOLIDWORKS^® Composer allows the LSST technical writer to assemble 3-D images through an associative link, thereby eliminating the need to update 3-D images in revisions. Images are updated automatically in the technical documentation, making the revision process very efficient (see Figs. 2 and 3).

Fig. 1

Technical Writing Process.

Fig. 2

SOLIDWORKS^® Composer: update current 3-D model of the M1M2 mirror.

Fig. 3

Automatic update of the M1M3 static support 3-D images with composer to the SOLIDWORKS^® CAD model revision.

During the process of developing technical documentation, SOLIDWORKS^® was updated without incident. The SOLIDWORKS^® Composer file references the SOLIDWORKS^® model.

The key benefit is that SOLIDWORKS^® and SOLIDWORKS^® Composer are associative. Any documents that link to the modified model, like procedures created in Microsoft Word^®, PDFs, etc., will update automatically regardless how drastic the changes are. The automatic update is for all 2-D and 3-D images as well as for 3-D interactive content and animations that have been created with SOLIDWORKS^® Composer.

Because SOLIDWORKS^® Composer 3-D images are linked to writing programs, such as word, all 3-D images of the word procedure are updated automatically to the new assembly revision (see Figs. 4 and 5). In this way, LSST technical documentation and animations are always kept up to date with any in-house or vendor driven design changes. LSST can get technical documentation faster with the assurance that our documentation is both high-quality and always up-to date.

Fig. 4

Microsoft Word^®: update links to SOLIDWORKS^® Composer.

Fig. 5

Microsoft Word^®: linked images to composer have been updated automatically.

7.

Implementation of Standardized Step-by-Step Instructions

Standardized step-by-step work instructions are used to formalize the work processes. Whether written up in numbered steps or formatted as flow charts, the LSST step-by-step instructions are complete, clearly written, and based on input from the SME or on-site technicians. When employees follow step-by-step instructions, for a particular job, they produce a product that is high quality and consistent. Standardized step-by-step instructions also minimize risk since they prevent unsafe deviations from the work process.

By displaying step-by-step construction procedures using 3-D images, ambiguities associated with traditional 2-D static images are eliminated. SOLIDWORKS^® Composer leverages existing 3-D design data to enable rapid development of clear and well-defined technical documentation. The example below shows the creation of 3-D images, with SOLIDWORKS^® Composer, to produce a clear step-by step procedure for the installation of the M1M3 mirror hardpoints. The 3-D images are created on the base of existing 3-D CAD models from the LSST engineering team or vendors. The created 3-D images are saved and can easily be implemented in the step-by-step procedures (see Figs. 6 and 7).

Fig. 6

3-D images saved in SOLIDWORKS^® Composer as JPGs and inserted in the word step-by-step procedure for the M1M3 hardpoints.

Fig. 7

Step-by-step procedure for the M1M3 mirror hardpoints, Microsoft Word^®.

8.

Interactive Bill of Materials and Direct Links to Commercial Off-the-Shelf

With SOLIDWORKS^® Composer, LSST is able to create dynamic technical documentation with interactive bills of materials (BoMs) with links to commercial off-the-shelf parts (see Fig. 8).

Fig. 8

Creation of interactive BoMs with SOLIDWORKS^® Composer for the M1M3 mirror actuator cups.

Within the interactive BoM, further information about a part can be found, like direct links to external vendor websites. Also, existing SOLIDWORKS^® BoMs can easily be imported to SOLIDWORKS^® Composer.

9.

Leveraging Existing SOLIDWORKS^® 3-D CAD Models

The 3-D CAD models are designed and developed by the LSST engineering team or vendors and are stored in the LSST product data management system, SOLIDWORKS^® PDM Professional. With the implementation of SOLIDWORKS^® Composer, we are able to create 3-D images for our technical documentation directly from our existing SOLIDWORKS^® 3-D CAD models (see Fig. 9). This implementation introduces an efficient and rapid process that creates easily understandable 3-D documentation. It conveys project schedules and trains workers more effectively and consistently. It also helps to minimize accidents, errors, and project rework.

Fig. 9

Create 3-D images with composer, by simply using existing SOLIDWORKS^® 3-D models.

10.

Cost Minimization

LSST has benefitted from several advantages using SOLIDWORKS^® Composer. LSST has seen a substantial cost reduction in writing and maintaining its technical documentation. Work that once required several individuals to keep updated now requires only a few. Also, by incorporating visually pleasing, high-quality images into the technical documentation, communication between engineers and technicians is simplified, allowing for the assembly of complex systems to proceed more quickly and with little difficulty (see examples of visual communication in Fig. 10).

Fig. 10

Examples of visual communication.

By creating detailed 3-D visual assembly and disassembly instructions that require only a minimum of text, LSST minimizes the cost of translation/localization for technical documentation. Visual communications minimize the need to provide complex written instructions or hand waving to educate field teams on construction procedures. Conveying instructions using detailed images has been shown to be more effective than the use of written or verbal instructions. Technicians with limited knowledge of English, or poorly detailed assembly procedures, can significantly benefit from the use of pictures. LSST has experienced these benefits, particularly in maintaining a high-level of safety, and an overall cost reduction at several levels of the documentation process. Although quantitative metrics are not available to evaluate the time saved by these methods, experience has demonstrated that this time is substantial.

11.

Unique Terminology by Importing 3-D Metadata

LSST has a well-established procedure for the creation of internal technical documents but maintaining similar capabilities from external vendors and subcontractors has proven difficult. The problem becomes exacerbated due to LSST global presence, working with foreign vendors, and the variety of software packages they use. Projects can often slip in schedule due to poorly conveyed instructions or insufficient technical documentation.

One challenging aspect of creating an updatable technical documentation database is obtaining similar documentation from LSST’s global subcontractors. These contractors have built highly complex subsystems and are required to supply operational documentation for these components. However, the typical workflow for creating technical documentation is highly inefficient and the technical documentation hard to understand. Due to these inefficiencies, projects become delayed, and installations proceed slowly or unsatisfactory and could compromise worker safety.

With SOLIDWORKS^® Composer, LSST can import 3-D metadata directly from existing 3-D CAD models. Metadata are part number, part name, material, parts supplier, and vendor web link. LSST engineers create 3-D models and directly enter 3-D metaproperties into SOLIDWORKS^®. The process is straightforward and easy. This metadata can easily be imported easily into SOLIDWORKS^® Composer by opening a 3-D CAD model and selecting the option “import metaproperties” (see Fig. 11).

Fig. 11

Import metadata from SOLIDWORKS^® to SOLIDWORKS^® Composer.

By importing metadata, we avoid inconsistent, ambiguous, and confusing naming in the technical documentation, and BoMs. All metadata properties used by LSST engineers, designers, subcontractors, and vendors use the same terminology, creating BOMs, which are understandable and can be easily transferable between all contributing partners (see Fig. 12).

Fig. 12

SOLIDWORKS^® Composer BoM with call-outs based on imported 3-D metadata from SOLIDWORKS^®.

12.

Interactive Fly-Through and Walk-Through Animations

LSST creates interactive animations to help explain complicated details of assembly instructions. Accurate video animations with SOLIDWORKS^® Composer have been highly effective for interactive training, and for instructions how to assemble, install, and maintain assemblies. An illustration of fly-through and walk-through animation processes is shown in Fig. 13. Interactive animations are exportable as PDF, and LSST adds the interactive animation to existing manuals. The process is straightforward and easy. For example, an assembly instruction of the LSST static support has been created, reducing a 20-min assembly process down to a 40-s interactive animation.

Fig. 13

Creation of an interactive animation with SOLIDWORKS^® Composer.

13.

Standard Safety Signs and Customized LSST Tools

Safety signs are essential for every technical documentation. By illustrating what tools to use and where to use them, identifying potential hazards or educating employees on best practices, LSST protects the health and safety of their workers and equipment while streamlining the construction process. SOLIDWORKS^® Composer offers a standardized safety library with ANSI conforming safety signs (see Fig. 14). These safety signs can easily be implemented into 3-D CAD drawings and be used as a 3-D image in technical documentation. The image libraries can also be customized. LSST implemented specific LSST tools into this library to address issues associated with telescopes and the adverse effects of working at altitude (see Fig. 15).

Fig. 14

Image library with standard safety signs.

Fig. 15

LSST customized image library with LSST tools.

14.

Customized Styles for Content Creation

Styles control specific elements in SOLIDWORKS^® Composer such as text, images, annotations, labels, call-outs, and interactive arrows (see example in Fig. 16). Creating styles is a time-consuming process, and the “look and feel” of the LSST technical documentation will vary when styles are created. To avoid this, LSST created their own style template and set those styles as defaults. Creating and using LSST standardized styles is an easy way to implement a unique “look and feel” of the LSST technical documentation.

Fig. 16

LSST customizes styles menu in SOLIDWORKS^® Composer.

In the styles workshop, you can quickly create a style from the properties of an existing model, apply or remove a style and set a default style for your SOLIDWORKS^® Composer document (see Fig. 17). The existing styles can be viewed in the styles’ menu (see Fig. 16). All styles are saved in the LSST product data management (PDM) system. They can easily be shared with subcontractors and collaborating agencies to create the technical documentation for LSST while having the same “look and feel” as an LSST created document.

Fig. 17

3-D model with LSST customized styles and SOLIDWORKS^® Composer workshop to define style layout.

15.

Standardized Templates

To ensure that LSST documentation is consistent, LSST created standardized templates with default document settings (see Fig. 18). With standardized templates, LSST implements a unique “look and feel” of the LSST technical documentation for quick reuse, avoiding the time-consuming process of recreating documents with no initial guidelines. Templates control the format of a document, whereas styles control the layout of images.

Fig. 18

LSST procedure template.

By having standard templates and settings, LSST eliminates ambiguity associated with different document formats from individual contributors. All LSST staff and vendors can use the same templates, settings, and styles.

16.

Automated Review and Approval Process

Quality assurance requires an official approval process for the technical documentation. With the SOLIDWORKS^® LSST PDM vault, LSST is able to implement an automated review and approval process for technical documents.

LSST is in the process of implementing an integrated workflow into the LSST PDM vault. Due to this implementation, the design and approval process will be automated, and reviews of final technical documents will be more formal, more efficient, and less time consuming.

The models are updated by LSST personnel to represent the as-built configurations through information provided by the vendors.

To ensure quality control, the models that are used in the technical documentation undergo a change control process, where they are extensively reviewed before approval. When a change occurs to a SOLIDWORKS^® model, the LSST technical writer/user of SOLIDWORKS^® Composer is notified automatically by the PDM system.

17.

Version and Configuration Control

LSST uses version and configuration control with the LSST PDM vault. 3-D CAD data is directly imported from SOLIDWORKS^® into the SOLIDWORKS^® Composer file. In this way, the 3-D CAD data is linked to the images in the actual technical documentation. SOLIDWORKS^® Composer files use the same work breakdown structure as the 3-D CAD files for easy identification. LSST can search for 3-D preview 3-D SOLIDWORKS^® Composer files directly inside the view tab in explorer or using search dialogue in the LSST PDM (see Fig. 19).

Fig. 19

Preview 3-D model in SOLIDWORKS^® Composer.

18.

Document Publishing

SOLIDWORKS^® Composer works seamlessly with Microsoft^®, Adobe^®, and other popular publishing software, allowing for smooth integration with other software packages. LSST can quickly publish the technical instructions in any of these formats:

19.

Conclusion

The implementation of a technical writing process and the authoring software SOLIDWORKS^® Composer is a great benefit for the LSST project. The technical documentation can be created at the very early design stage and changed automatically if a design change occurs. LSST has seen a substantial cost and time reduction in writing and maintaining its technical documentation. Work that once required several individuals to keep updated now requires only a few. By illustrating what tools to use and where to use them, LSST protects the health and safety of their workers and equipment while streamlining the construction process. All involved systems for the technical documentation creation are working very well together, from the LSST PDM vault, to SOLIDWORKS^® and SOLIDWORKS^® Composer, to our document and content management system DocuShare^®.