Become a Great Technical Writer
even if you are not a great writer

Are you contemplating or beginning a career in technical writing? Have you been asked to create the user guide for your company's software application? Have you been asked to hire and manage a writer?

Where do you begin? How can you get an interview when you have no experience? How do you know if the technical writer on your team is doing a good job or a poor one? Can you find out before you hire the person?

Technical writers (known as technical authors in the United Kingdom) translate and organize complex information into user guides that any person can understand and use with ease. But in the 16 years that I have been in the business, I have often found myself working with writers who do not really know how to write manuals or use the desktop publishing software, and with clients who are not entirely sure what to expect from writers. More often, I have had to clean up a documentation mess left behind by a previous writer. This asymmetry between expectation and output can create technical writers who unknowingly make the same costly mistakes year after year, and clients who regard technical writers as a high-cost, low-value drain on the company's bottom line.

This site, whether you are a manager or a technical writer, will get you all working on the same page. If you are a writer, you will see that technical writing requires skills other than the ability to write. In fact, it is possible to write great user guides even if you are not a great writer. You don't need to spell perfectly (I don't), and you don't need to know the difference between a dangling participle and a dangling gerund. But although you don't have to be a great writer, you will probably be happier in the job if you like writing and are a competent writer. If you find it difficult to organize your thoughts and put them down in writing, you might find the job boring, unpleasant, and unrewarding.

In fact, writing is only a fraction of what you will do as a technical writer. This site, therefore, does not show you how to become a great writer—many other sites exist to help you with your grammar and style—but it does provide you with information, skills, tips, and techniques that can help you become a great technical writer.

Notes For Managers
If you are a manager, this site shows you what you can expect from the technical writers on your team. Although this site speaks mainly to the writer, you will easily be able to develop from the information provided your own expectations and requirements for your writers. This site will also help you distinguish between good and bad technical writing and it will tell you what to look for when hiring a writer. In particular, you should read the first three articles below.

:: 관련 링크 ::
http://www.docsymmetry.com/index.html

Docsoft's W2XML!

Docsoft's W2XML software is Word-to-XML conversion software. It converts DOC and RTF formats to well-formed XML. It is completely scalable and allows for custom XML exporting by allowing you to create and apply custom XSLTs to modify the standard output. W2XML supports the conversion of Microsoft Equation objects to MathML! The additional support for converting Microsoft(R) Equation objects into MathML (a W3C standard for describing mathematic formulas in a format easily transmittable over the web) augments W2XML's existing conversion capabilities unmatched by other Word-to-XML conversion tools.

Produce Docbook-Compliant Output

The software comes with an XSLT that allows you to output Docbook-compliant XML (http://www.docbook.org/) from most Word documents. This software will help you convert your legacy data for use within the Docbook framework with minimal effort.

"Our project at AT&T required us to transform format-intensive customer documents to clean (well-formed and valid) DocBook XML (Version 4.2), and to do this without contending with expensive and complicated software, training, etc. W2XML satisfied this objective. After telling W2XML the filename(s) of the Word document(s) to be translated and the name of a custom XSLT, we can now generate the DocBook XML with the click of a mouse. And, with this available DocBook XML, we can apply another XSLT (which we coded) to translate the XML to Web-ready XHTML in a matter of seconds."

- Jim Gregg AT&T Technical Information Design and Development

Use Word as an XML Editor

You can also export to practically any Schema you wish by using W2XML's abilities to capture named styles within Word. When the Word document is converted to XML, class attributes area also added to each element. The value of the class attribute is the style name that is applied within Word. This ability turns Word into an XML editor. All you need to do is create a template (*.dot) within Word and create styles with the same names to match your Schema or DTD, and then apply the styles to each area as you are authoring in Word.

For instance, let's say you have an XML Schema or DTD that has 3 elements (for simplicity, we will only use 3 elements). The element names are title for titles, para for paragraphs and ulist for un-numbered lists. You can create styles in Word with these same names and apply the styles during the authoring process. When the *.doc is exported to XML using W2XML, these style names appear as attributes, which can easily be transformed to elements using XSLT.

W2XML has the most features for the money, and is the easiest-to-use Word to XML converter available.

Why Convert to XML?

Organizations are using XML for storing their data in a structured manner. This makes the documents "intelligent" and provides the capability of automating data transfer, searching and retrieval. It also automates processing and repurposing of the information that is contained with the documents. Another considerable advantage is that data tagged as XML today will still be useable 10, 15 even 20 years from now, because it is truly *extensible*.

The number one word processing software is Microsoft's Word. The number one method of storing intelligent documents is XML. Combine the two, and you give your organization a tremendous amount of data capabilities.

Unicode Character Support

W2XML supports most Unicode charsets, such as Arabic, Cherokee, Cyrillic, Danish (umlauts), Deutsch, Greek, Hebrew, Western, and some Asian character sets.

What About Word 2003?

While the prospect of being able to use Word 2003 to map and export XML is exciting, it does not provide an easy means of converting existing or legacy Word documents to XML. W2XML can bridge this gap for you, making it easy to export pure XML data from your MS Word documents. One of the best features of W2XML is that you can create a custom XSLT to automatically convert the standard output to your specific XML Schema, so you can create a single XSLT to "map" all of your Word data correctly, rather than having to map each individual Word document to XML using Word 2003!

W2XML Free Trial

W2XML is available for a free trial! To download a demo version, all you need to do is visit our Online Store and download the trial software. You will have 30 days to evaluate the software, and you can only convert up to 3 documents each time the application is launched.

W2XML System Requirements

Please review the following requirements to ensure optimum application performance and operability:

• Windows Platform w/.NET Framework 1.1;
• 500M RAM;
• 500K of hard disk space;
• Word 2K, XP or 2003 installed on host system;
• Mouse or suitable pointing device;
• Good understanding of eXtensible Style Language to create XSLTs for custom output.

NOTE: Customers who use W2XML to convert Word to XML must understand the relatively complex concepts behind conversion from an unstructured format to a structured format. For this reason, Docsoft recommends that customers who are new to structured content, or do not have the expertise to develop sometimes complex XSLTs, contract with Docsoft's consulting services to develop XSLTs to convert the standard output to a Schema or tag set for your specific needs. You may also visit our Techspeak Forums for questions and answers to this software and how to implement custom XSLTs.

W2XML v2.5 Update

NOTE:: This section is no longer updated. Please use the Techspeak Forums to access updated XSLTs, request information about upgrading or submit your own XSLT for others to try.

W2XML v2.5 Release Information

Users who purchased W2XML v2.0 or above may upgrade to v2.5 for free. See "Free Upgrade to Previous W2XML v2.0 Users" below for details.

Please see the W2XML v2.5 Documentation for information on the newly-added functionality.

Related URL
http://www.docsoft.com/w2xmlv2.htm

오픈도큐먼트로 향하는 세계「한국은 조용∼」
정진옥 기자 [2006/02/07]

전 세계 도시들의 오픈도큐먼트 지원 바람…한국 정부와 업체들 '신중론'

표준화 단체인 OASIS(Organization for the Advancement of Structured Information Standards)가 개발한 오픈도큐먼트(OpenDocument)가 전 세계 도시로 확산될 조짐이다.

잇단 오픈도큐먼트 채택은 지난해 9월에 미국 미국 메사추세츠 주가 주 정보의 소프트웨어 구매 시 오픈도큐먼트를 지원하도록 의무화한다고 발표하면서 촉발됐다. 이어서 독일 만하임시도 비용이 아닌 '공개' 표준에 대한 선호 때문에 도시 전체가 리눅스로 옮겨가고 있으며 오픈도큐먼트를 지원하는 오픈오피스로 전환한다고 발표했다. 이러한 물결은 덴마크나 노르웨이를 포함한 유럽 각국의 정부, 일본, 그리고 메사추세츠 주 이외의 미국 다른 주에까지 퍼져나가고 있다.

지난 5월에 표준이 승인된 XML 기반의 오픈도큐먼트는 워드 프로세서, 스프레드시트, 프레젠테이션 소프트웨어 등의 데스크톱 애플리케이션 저장을 위한 문서 포맷들의 집합이다.

MS 견제할 개방형 표준 '오픈도큐먼트'
오픈도큐먼트는 데스크톱 애플리케이션 시장에서 지배적인 위치를 차지하고 있는 MS를 점점 궁지에 몰아넣고 있다는 점에서도 관심을 끌고 있다.

글로벌 업체인 IBM과 썬, 구글을 비롯해 노벨, 코렐, 어도비 시스템즈 등이 오픈도큐먼트 지원 의사를 밝혔다. 썬은 오피스 스위트인 스타오피스에서 오픈도큐먼트를 지원하고 있고, IBM도 데스크톱 제품인 워크플레이스에 사실상의 표준으로 채용할 계획이다. 또 오픈 소스인 오픈오피스도 오픈도큐먼트를 채용하고 있다.

반면 MS는 올해 하반기에 출시 예정인 오피스 '12'에서 오픈도큐먼트를 지원할 의사가 없다는 입장을 고수하고 있다.

물론 끊임없는 오픈도큐먼트의 공격에 대항해 MS도 두 손 놓고 있지는 않다. 애플컴퓨터, 바클레이 캐피털, BP, 영국도서관, 에실러, 인텔, 넥스트페이지, 스테이토일, 도시바 등이 후원하는 ECMA 인터내셔널 기술위원회를 출범해 오피스 오픈 XML 포맷을 표준화하려는 작업을 서두르고 있다.

하지만 오픈도큐먼트를 지원하는 기업들이 늘고, 세계 여러 도시들이 이러한 추세로 나아가 오픈도큐먼트가 표준으로 자리를 잡게 된다면 MS 오피스의 자리는 급격히 줄어들 수 있을 것이기 때문에 MS로서는 좌불안석일 것이다.

정보화의 주권 되찾겠다
각국 도시들이 오픈도큐먼트 같은 개방형 표준을 채택하는 것은 여러 가지 이유가 있다. 우선은, 상용 소프트웨어의 업그레이드를 위해 불필요한 라이선스 비용을 지불하지 않아도 되기 때문이다. 여기서 절약한 돈을 의료나 교육과 같이 더욱 중요한 다른 활동에 투입할 수 있을 것이다.

또한 공공 문서가 특정 독점 프로그램에 의존해선 안 된다는 인식도 한몫 했다. 그럼으로써 원하는 소프트웨어 애플리케이션을 선택할 수 있는 권한과 호환성이 높아질 것이다.

독일 만하임시의 IT 인프라스트럭처 관리자인 게르트 아름브루스터는 "우리가 만하임의 IT 전략을 결정하고 싶은 것이지, MS가 만하임을 위해 결정을 내려주길 바라지는 않는다"고 말했다.

정통부 "결정된 바도 없고, 쉽게 결정할 사안도 아니다"
이에 비해 우리나라는 오픈도큐먼트에 대해 매우 신중하고 조심스러워 아직 명확한 입장 표명을 하지 않고 있다.

정통부 소프트웨어진흥팀의 이도규 서기관은 "쉽게 판단할 문제가 아니다"며 "국제 표준으로서 좀더 성숙되는 것을 지켜본 후에 판단해도 늦지 않을 것"이라는 입장을 밝혔다.

이 서기관은 아직 다른 나라에서도 지방 정부 단위에서 시행하고 있을 뿐, 중앙 정부 차원까지 확대한 곳은 없으며, 우리나라에서도 올해 공개 소프트웨어 시범 도시 지정에 이런 과제를 포함할 수도 있을 것이라고 전했다.

현재 우리나라 공공 기관에서는 오피스 프로그램으로 MS의 오피스와 한글과컴퓨터의 오피스 두 가지를 사용하고 있다. 정통부 측은 수치를 밝힐 수는 없지만, 한컴 오피스 사용 비율이 그다지 적지는 않다고 말했다.

오픈도큐먼트의 의미는 충분히 알고 있지만, 실제 실현 가능성이나 장·단점, 비용 등 고려해야 할 문제들이 만만치 않아 좀더 신중하게 검토해야 한다는 입장이다. 따라서 올해 정책 연구 과제 중 하나로 오픈도큐먼트 관련 시범 사업이 제안되기는 했지만, 이것이 공식 채택된 상태는 아니라 연구 과정이 언제 시작될지도 알 수 없는 노릇이다.

이도규 서기관은 "전제가 돼야 할 것은 국내 소프트웨어 산업 육성에 이바지해야 한다는 점"이라고 못박으며 "동향에 대한 검토는 꾸준히 하고 있지만, 한글과컴퓨터 같은 국내 오피스 제작 업체들이 오픈도큐먼트 지원에 대한 준비가 됐을 때 구체적으로 검토할 수 있을 것"이라고 말했다.

토종 오피스 업체들 "개발 관련 중대한 이슈…신중, 또 신중"
오픈도큐먼트 지원과 관련해 국산 오피스 개발 업체들의 입장도 신중 일변도다.

국내 대표 오피스 프로그램 업체인 한글과컴퓨터는 "긍정적인 방향으로 검토하겠다"는 입장만을 밝혔다.

한컴의 양왕성 이사는 "기술적으로 문제가 있는 것은 아니지만, 회사의 정책이나 개발 일정과 관련해 여러 가지 사항을 검토중"이라면서도 "올 중반기쯤 새 오피스 제품이 발표될 시기에는 중대한 발표를 할 수도 있을 것"이라고 말해 여운을 남겼다.

자바를 기반으로 한 국산 오피스 제조 업체인 테크다임 역시 아직 명확한 노선을 결정하진 못했다.

테크다임의 류상범 이사는 "파일 포맷을 공개한다는 것은 크게 상관 없지만, 고유의 파일 포맷을 포기하고 새로운 포맷을 받아들여야 한다는 점은 개발 측면에서 쉬운 결정이 아니다"며 "외국 수출을 위해서도 오픈도큐먼트 지원은 꼭 필요한 사항이지만 아직 결정한 바는 없으며, 올해 시작될 우리오피스 2005의 차기 버전 개발 시에 오픈도큐먼트 지원 여부를 결정하게 될 것"이라고 전했다.

비용 문제를 비롯해 개발 측면의 문제, 시장 역학 관계, 기존 고객 문제 등을 총체적으로 고려할 때 문서 형태를 변환한다는 것은 개발뿐 아니라 비즈니스와 관련한 굉장한 이슈이며, 따라서 세부적이고 중대한 논의 과정을 거쳐야 한다는 것이 정통부와 업체 관계자들의 입장이다.

오피스 제품 개발 업체들은 신중한 태도를 견지하면서 아직 결정된 바가 없다고 말하지만, 두 업체 모두 올해 신제품 개발을 앞두고 있음을 간과할 수 없다. 전 세계적인 흐름을 감안한다면 이들의 신제품 계획에 어떤 식으로든 오픈도큐먼트의 손길이 미칠 것으로 보인다. 그들은 MS가 아니지 않은가. @

"기술 전문 저술가" [技術專門著述家, technical writer]

정보 기기 또는 전자 기기에 관한 기술적인 내용을 일반적인 경향으로 알기 쉽게 설명하고, 과부족 없이 정보를 제공하기 위한 문서를 쓰는 사람.

엠파스 IT용어사전에서 검색한 것이다.

현재 내가 일하고 있는 직군이 이것인데.. 흔히들 메뉴얼 제작하는 것만 생각할수도 있다.
내가 일하고 있는 부분은 Component Software 를 활용하여 Application 을 쉽게 개발할 수 있도록
Guide 를 제시해주는 문서를 만들고 있다. 뿐만아니라 Software Engineering Process 중에 투입되어
개발자들이 설계문서를 작성하는데 Writing 이나 Documentation 관련된 부분에서 Support 를 하고 있다.  

Technical writer