Embed Size (px)
DESCRIPTION
A presentation about the technical writing basics. Author: Jordan Stanchev, SAP Labs Bulgaria.
Citation preview
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
© 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.
