Download to read offline
Uploaded byBryan Hughes
Effective Documentation for Open Source Projects
The document emphasizes the importance of effective documentation in open source projects, underscoring that user knowledge can vary significantly. It provides guidelines for structuring documentation, covering essential components such as introduction, installation, usage, API documentation, and details on various coding elements. The successful implementation of these documentation practices greatly contributes to the project's success.
Effective Documentation for Open Source Projects
- 1. Effective Documentation forOpen Source Projects Bryan Hughes, Ph.D. Microsoft @nebrius aka.ms/nebrius-nceu18
- 2.
- 3.
- 4.
- 5. Parts of aREADME
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
- 15.
- 16.
- 17.
- 18.
- 19. aka.ms/nebrius-nceu18 Algorithm •Start w/ moduleexports •Recursively descend •End with primitives
- 20. aka.ms/nebrius-nceu18 Example API Tree moduleexports function init string NAME Class Badge bool successstring connect bool retry string name bool connected number backlight arguments return constructor properties
- 21.
- 22.
- 23. aka.ms/nebrius-nceu18 Objects •Each property’s name •Eachproperty’s value •Bonus: prototype
- 24.
- 25. aka.ms/nebrius-nceu18 Event Emitters •Each event’s name •Eachevent’s arguments
- 26.
- 27. Documentation is key tosuccess
- 28.
Editor's Notes
- #7 Project Summary Why you should use it Badges
- #9 OS+Node.js version Non-npm dependencies Hardware reqs/peripheral reqs
- #11 npm Command in ``` Root/Admin privileges? Different variants?
- #13 Short example(s) Most common use case Description of code
- #15 Known edge cases Common bugs Non-obvious tips
- #17 Fully documents all Props, methods, events Types of everything