GuideAutomator: Continuous Delivery of End User Documentation

Slides presented at the 39th International Conference on Software Engineering (ICSE 2017), NIER Track (New Ideas and Emerging Results), in Buenos Aires, Argentina.

Paper: https://rodrigorgs.github.io/files/icse-nier2017-rodrigo.pdf
Poster: https://rodrigorgs.github.io/files/nier17-guideautomator-poster.pdf
Video: https://youtu.be/hjNiQJ4_iOY

Abstract: User guides, also known as user manuals, are a type of documentation aimed at helping a user operate a specific system. For software systems, user guides usually include screenshots that show users how to interact with the user interface. Because creating such screenshots is a slow, manual process, keeping the user guide up-to-date with changes in the user interface is challenging. We propose an approach in which the documentation writer interleaves the user guide text with source code that automates screen capturing. As a result, screenshots always reflect the latest software version, which makes the approach suitable for a project that uses continuous delivery. The approach was implemented as a prototype, called GuideAutomator.

Transcript

1. GuideAutomator:
 Continuous Delivery of
 End User Documentation Rodrigo Souza* Allan Oliveira Federal University of Bahia (UFBA) ICSE 2017, NIER Track November 25, 2017 Buenos Aires, Argentina Federal University of Bahia (UFBA), Brazil Department of Computer Science Software Design and Evolution Group (aSide) * rodrigo@dcc.ufba.br / @xrodrigorgs
2. Write the user guide! Now!
4. What’s in a user guide?
5. step step step step screenshot screenshot screenshot screenshot task
6. screenshot screenshot screenshot screenshot step step step step
7. screenshot screenshot screenshot screenshot
8. Paper Management System (4 screenshots)
9. How to create a screenshot for a user guide?
10. Open the application
11. localhost:3000 Open the application
12. Create sample data
13. Create sample data Go To statement considered ha Dijkstra Do not use goto.
15. On the criteria to be used when Parnas Keep together what changes t
16. Follow steps in user guide
17. Follow steps in user guide
18. Follow steps in user guide
19. Follow steps in user guide
20. Follow steps in user guide
21. Follow steps in user guide GuideAutomator Rodrigo, Allan Continuous delivery of user documentation.
22. Follow steps in user guide GuideAutomator Rodrigo, Allan Continuous delivery of user documentation.
23. Take the screenshot
24. Take the screenshot
25. Capture the screen Crop
26. Capture the screen Crop
27. Crop
28. Highlight
29. Highlight
30. Paste the image in the document
31. Paste the image in the document
32. How much time? (4 screenshots)
33. Traditional create
34. Traditional create 5 min
35. What if the UI changes?
36. What if the UI changes?
37. Change font Change font What if the UI changes?
38. Change font Change font What if the UI changes?
39. Traditional create 5 min update ?
40. Traditional create 5 min update ? 5 min
41. Traditional create 5 min update ? 5 min updating screenshots for a user guide is as painful as creating them
42. Continuous delivery
43. Software applications must be continually adapted Lehman, 1974
44. Software applications must be continually adapted Lehman, 1974 … and then released to users!
45. Continuous delivery Every change should be releasable
46. Continuous delivery Every change should be releasable That means updating the user guide if necessary!
47. User guides Continuous delivery
48. User guides Continuous delivery
49. GuideAutomator
50. GuideAutomator Command-line tool to automate the creation of screenshots for web applications.
51. Traditional approach You take and edit screenshots
52. Traditional approach You take and edit screenshots GuideAutomator You write code that takes and edits screenshots
53. input.markdown code(...); moreCode(…,…);
54. input.markdown code(...); moreCode(…,…); Selenium Web Driver Chrome GuideAutomator
55. input.markdown code(...); moreCode(…,…); output.html Selenium Web Driver Chrome GuideAutomator
56. Plain text formatted with Markdown plain text
 (using Markdown)
57. source code chunk (in JavaScript, using GuideAutomator’s API) source code chunk
 (using GuideAutomator API)
58. API commands
59. identify elements by CSS selectors
60. How much time? (code for 4 screenshots)
61. Traditional Guide Automator create 5 min update 5 min ?
62. Traditional Guide Automator create 5 min update 5 min ? 10 min
63. Traditional Guide Automator create 5 min update 5 min ? 10 min It took longer!
64. Change font Change font What if the UI changes?
65. Traditional Guide Automator create 5 min update 5 min 10 min
66. Traditional Guide Automator create 5 min update 5 min 10 min 25 s
69. Additional benefits
70. Additional benefits User guides can be integrated in an automated build process
71. Additional benefits User guides can be integrated in an automated build process The build can break because of outdated documentation
72. Experiments
73. 2 participants
 13 screenshots 1 version Pilot experiment #1
74. 2.2x longer with GA 2 participants
 13 screenshots 1 version Pilot experiment #1
75. Pilot experiment #2 2 participants
 15 screenshots 2 versions
76. Pilot experiment #2 2 participants
 15 screenshots 2 versions 0 7,5 15 22,5 30 v1 (create) v2 (update) GA Traditional min GA Traditional
77. Pilot experiment #2 2 participants
 15 screenshots 2 versions 0 7,5 15 22,5 30 v1 (create) v2 (update) GA Traditional min GA Traditional
78. Plans for the future
79. Future MSR study Build user guide for each commit
80. Future MSR study Build user guide for each commit How often do screenshots need to be updated?
81. Future MSR study Build user guide for each commit How often do screenshots need to be updated? How often does the user guide break the build?
82. Browser extension Writes GuideAutomator code as you interact with the browser https://github.com/welbert/guide-automator-addon
83. Other platforms Desktop Mobile
84. Other
 outputs Technical books Slides Video
85. User guides Continuous delivery
86. User guides Continuous delivery
87. User guides Continuous delivery Guide Automator
88. https://github.com/aside-ufba/guide-automator rodrigo@dcc.ufba.br