Documentation is critical in creating a successful open source project, yet it can be hard to know where to start. How do you organize your docs? What sections do you need? How much detail should you add? What baseline knowledge can you assume your audience has? This talk will walk you through how and why to document a typical JavaScript module in npm for the browser or Node.js

1. Effective Documentation for Open
Source Projects
Bryan Hughes, Ph.D.
Microsoft
@nebrius
aka.ms/nebrius-nceu18

2. Mindset

3. aka.ms/nebrius-nceu18
You are not
your users

4. aka.ms/nebrius-nceu18
User knowledge
is highly variable

5. Parts of a README

6. aka.ms/nebrius-nceu18
Introduction

7. aka.ms/nebrius-nceu18

8. aka.ms/nebrius-nceu18
System Requirements

9. aka.ms/nebrius-nceu18

10. aka.ms/nebrius-nceu18
Installation

11. aka.ms/nebrius-nceu18

12. aka.ms/nebrius-nceu18
Usage

13. aka.ms/nebrius-nceu18

14. aka.ms/nebrius-nceu18
Notes

15. aka.ms/nebrius-nceu18

16. aka.ms/nebrius-nceu18
API

17. aka.ms/nebrius-nceu18

18. Complete API
Doc Guidelines

19. aka.ms/nebrius-nceu18
Algorithm
•Start w/ module exports
•Recursively descend
•End with primitives

20. aka.ms/nebrius-nceu18
Example API Tree
module exports
function init string NAME Class Badge
bool successstring connect
bool retry
string name bool connected
number backlight
arguments return constructor properties

21. aka.ms/nebrius-nceu18
Primitives
•Type
•Default Value?
•Optional/Required?
•Value limits?

22. aka.ms/nebrius-nceu18
Functions
•Return value
•All arguments
•Bonus: does it throw?

23. aka.ms/nebrius-nceu18
Objects
•Each property’s name
•Each property’s value
•Bonus: prototype

24. aka.ms/nebrius-nceu18
Classes
•Everything from Objects
•Constructor
•Overridable functions

25. aka.ms/nebrius-nceu18
Event
Emitters
•Each event’s name
•Each event’s arguments

26. aka.ms/nebrius-nceu18
Promises
•Resolve arguments
•Each rejection’s arguments

27. Documentation
is key to success

28. @nebrius