Functional Design for Developer Documentation. Ulrike Parson

Transcription

1 Functional Design for Developer Documentation Ulrike Parson 1

2

3 Expectations What is developer documentation? Documentation written for software engineers Explains how to program/customize a specific application based on an API Target audience knows how to program, it may not know the specific application and may not know the domain Why are you here? 3

4 Theoretical Background of Funktionsdesign Developer Documentation: Target Groups and Information Types Applying Funktionsdesign to Developer Documentation 4

5 Theoretical Background of Funktionsdesign Developer Documentation: Target Groups and Information Types Applying Funktionsdesign to Developer Documentation 5

6 Speaking (writing) is acting Every sentence has a function (intention). The function is not always clear. The door is open. I just realized. It s your fault. You left it open. Go and close it. Please come in. Intention clear Successful communication 6

7 Four-sides model of communication By JazzyJulius - Translated from which in turn was based on Public Domain, 7

8 Technical writing must be explicit We need to make our intentions clear and assign an explicit function to each text: Inform Instruct Teach Provide facts Express permission or prohibition Request for action. 8

9 History Funktionsdesign : History and Purpose Developed by professors Jürgen Muthig (University of Karlsruhe and Robert Schäflein-Armbruster (University of Furtwangen) as a method for standardizing and structuring technical documentation Scope and Purpose Systematic approach for developing standardized documentation elements on different levels and writing rules Makes document creation more efficient Makes documentation shorter, more concise and more consistent Improves readability and comprehensibility Happier readers 9

10 What can be standardized? Document structures Layout Language Authoring and reviewing processes 10

11 Levels of Structuring Information Document Macro structures (e.g. topic or table) Matryoshka principle Structures at each level have distinct functions. Micro structures (e.g. markup) 11

12 Document Structure Document Macro structures Micro structures 12

13 Standardizing Documents Document = discrete piece of content that is about a specific subject, has clearly identifiable functions, and can stand alone. A document should tell a story. It answers central questions. What is the context? What is it about? Who is it for? Why is it important? What is the reason? What needs to be done? How is it done? What is the meaning of? 13

14 Standardizing Documents Which other sources of information do I need to reference? What are the regulatory requirements? Which sections do I need in every document of this type? Which information should be excluded from the document? What to standardize? Document structure Mandatory and optional sections/structures Document metadata Medium and layout Authoring and reviewing process 14

15 Documents in Content Delivery Portals Topics need context Collection of topics = provides context Table of contents navigates through collection and provides information about sequence of topics More general information on uppermost level 15

16 Macro Structures Document Macro structures Micro structures 16

17 Macro Structures Copyright Technical Data Procedures Concepts Safety information Figures Lists Tables Title Figure title Procedure step Step result List introduction List item Table entry 17

18 Standardizing Macro Structures What is the central idea of each section or macro structure? Can the reader immediately recognize the function of a section or structure based on styling and wording? What to standardize? Function and internal structure of mandatory sections Writing rules and conventions How to write a procedure How to write a use case for a programmer How to write a class reference 18

19 Exercise Form Follows Function Lorem ipsum dolor sit amet: consetetur sadipscing elitr sed diam nonumy eirmod tempor invidunt ut labore et dolore magna Lorem ipsum dolor sit amet: 1. Aliquyam erat, sed diam voluptua. 2. At vero eos et accusam et justo duo dolores et ea rebum. 3. Stet clita kasd gubergren, no sea takimata sanctus. Lorem 1AC6_A 3JSae_F JS4GF_G ipsum est Lorem ipsum dolor sit amet at vero eos et accusam et justo takimata sanctus est Lorem Est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr. 15/6 clita kasd gubergren 16/01 justo duo dolores 15/10 at vero eos 19

20 Notes and warnings ANSI Z535 and ISO (hardware, machinery) Software documentation (example) Property damage, data loss Notes that need to be followed. Hints that make your work easier. 1. Signal word and symbol. 2. Kind and source of danger. 3. Consequences if you do not follow the warning information. 4. What you need to do to avoid the danger. 20

21 Micro Structures Document Macro structures Micro structures 21

22 Micro Structures Product or component names Names of classes, parameters, functions, commands Values and units Dates Cross references File names Abbreviations 22

23 Know your Audience! 1. Identify and describe the target audience of your document type. 2. Analyze the requirements of the target audience. 3. Check if document meets the requirements. 23

24 Questions to Ask Who reads the document? Are there different types of users? How do they read the document? What does my target audience need to know? What level of education does my target audience have? Are they familiar with terms used in the document? Which types of information will they expect? In which scenarios will the document be read? For API documentation: What does my audience already know regarding the domain and regarding programming? For English documentation: What is the level of English proficiency of my target audience? The results of the target group analysis determine which document/macro/micro structures you need for your documentation! 24

25 Theoretical Background of Funktionsdesign Developer Documentation: Target Groups and Information Types Applying Funktionsdesign to Developer Documentation 25

26 What are your Target Groups? Junior Software Engineers Experienced Software Engineers No engineers, but with domain knowledge and maybe programming skills Managers responsible for decisions related to using the API Junior Developer Senior Developer Domain expert Manager / CTO 26

27 Structures for Developer Documentation Level Structures Junior Dev Senior Dev Expert Manager Document Macro Micro Features and Benefits X X Getting Started Class reference X X Tutorials X X Terms of use Concept X X X Tutorial X X Code sample X X Workflow X X X Task X X Warning X X Inline Code X X X 27 X

28 Example of API Doc focused on Target Group 28

29 Our Sample API JIRA Rest API: Copyright of Atlassian Acceptable Use Policy: 29

30 Exercise: Recognize Level and Target Group Form groups and do the following exercise together. Scan the sample from the JIRA Rest API documentation Identify the function and target group of the marked elements Any thoughts on the layout and text structures of the documentation? 30

31 Solution: Recognize Level and Target Group 31

32 Exercise: Who needs what matrix Level Chapters Target Group Target Group Target Grop Document Develop a who needs what matrix for your documentation Which target groups do you have? Which sections do you need? Which target group needs which section? Which sections to summarize in a separate document? 32

33 Discussion: Template for Task Standardization on the macro level Which sections do you need, which need to be mandatory? Who reads tutorials? Do we need warnings with different warning levels? Where to present related information? Standardization on the micro level Numbered steps? How to write the titles of tutorials? How to present code samples? 33

34 Sample Template for Tutorials 34

35 Exercise: Write Use Case Prerequisites: We have a style guide with a macro structure for use cases. We have identified the target audience(s) for our documentation. We have researched the use cases that are interesting for our target audience(s). Exercise: 1. Form groups. 2. Analyze the input text with the explanation on how to create an issue Read the style guide instructions on how to write a use case. 4. Fill in the information from the input text into the style guide template. 5. Present result to the group. What are your findings? 35

36 Solution: Write Use Case Identify missing information Make prerequisites clear. Notes at the beginning. Related information at the end. 36

37 Research on Developer Documentation Research project of University of Merseburg: API documentation What software engineers can teach us. by Stephanie Steinhardt, Andreas Schubert, Michael Meng 37

38 Research on Developer Documentation Some findings Different reading types: some read concepts, others directly dive into the programming examples Pages are not read line by line, but scanned (Remark: Funktionsdesign helps, because topics with a standardized structure are much easier to scan) Code is read first. Only if it does not work, the rest is read as well. Complicated document structures make understanding more difficult Classification into document types, e.g. Developer guide, Getting Started, Recipes, Tutorials, not always helpful >> better to arrange topics around the subjects Titles must be clear General overview of API and first steps are essential Navigation is the key to understanding Domain knowledge is essential >> concept topics needed 38

39 Questions? 39

40 Ulrike Parson parson AG Chrysanderstr. 69A Hamburg XING, LinkedIn +49 (0)