Technical Writing BasicsJordan StanchevSAP Labs BulgariaDecember, 2013

© 2013 SAP AG. All rights reserved. 2Public

The User Experience and Documentation

Great tool, I know what will happen

when I click on the X sign.

Oops… What do I do now?!

© 2013 SAP AG. All rights reserved. 3Public

Documentation

Software documentation or source codedocumentation is written text thataccompanies computer software.It either explains how it operates or how to use it, andmay mean different things to people in different roles

Source: http://en.wikipedia.org/wiki/Software_documentation

© 2013 SAP AG. All rights reserved. 4Public

Technical Writer

A technical writer (also called a technical communicator)is a professional writer who engages in technical writing andproduces technical documentation.

The Institute of Scientific and Technical Communicators hasdefined the profession as preparing information which helpsusers.

Source: http://en.wikipedia.org/wiki/Technical_writer

© 2013 SAP AG. All rights reserved. 5Public

Documentation in the Software Development Process

Writes & preparesdocumentationdeliveryReviews strings on thescreenCreates proposals forembedded information

DevelopsthesoftwareTests theimplementation

Designsthe UI

Collects andorganizes therequirements fordevelopment

© 2013 SAP AG. All rights reserved. 6Public

Target Your Audience

Who are you writing for?What does he/she needs to achieve?What does he/she need to actually do to achievethe goal?What are the concepts that the user needs toknow?What is the additional, reference informationneeded for that?

© 2013 SAP AG. All rights reserved. 7Public

Information Modules

Write one task in a single topic.

Write conceptual information separate from thetask.

Write reference information in separate topics.

© 2013 SAP AG. All rights reserved. 8Public

UI String Review

Clarify what is thedifference between

them, if any.

Add tooltip and label“Create” on the button.Even better will be to

remove the arrow.

Show a confirmation messageupon successful creation of a

task

© 2013 SAP AG. All rights reserved. 9Public

Information Modules

Task

Reference

Concept

© 2013 SAP AG. All rights reserved. 10Public

Documentation Examples

http://help.sap.com/nw74/

https://help.hana.ondemand.com

© 2013 SAP AG. All rights reserved. 11Public

The User Experience with Documentation

Great tool, I know what will happen

when I click on the X sign.

Oops… Whatdo I do now?!

Have a question?

Jordan Stanchev

Knowledge Architect, SAP Labs Bulgaria

jordan.stanchev@sap.com

© 2013 SAP AG. All rights reserved. 13Public

© 2013 SAP AG. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG.The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

National product specifications may vary.

These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation orwarranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Groupproducts and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothingherein should be construed as constituting an additional warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG inGermany and other countries.Please see http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademark information and notices.