Docs vs Tooling - Speaker Deck

Slide 1

Slide 1 text

Docs vs Tooling — How You can Support Developers to Effectively Use Your Code By Victor Ikechukwu

Slide 2

Slide 2 text

I am Victor Ikechukwu. I code and write about code. 2 Hell0! 👋 www.iamvictor.tech @Victor_codejs

Slide 3

Slide 3 text

Table of contents ✗ What is Documentation? ✗ Why you need Documentation, and its beneﬁts ✗ What is Tooling? ✗ Examples of Tooling and their beneﬁts ✗ How you can combine both Documentation and Tooling to better support the developers that’ll use your code 3

Slide 4

Slide 4 text

WHAT IS DOCUMENTATION? 11

Slide 5

Slide 5 text

Documentation refers to all the materials that explains how our code works and how it should be used. 5

Slide 6

Slide 6 text

How is documentation helpful? 11

Slide 7

Slide 7 text

7 It helps others to use your code

Slide 8

Slide 8 text

8 It enable others to help out

Slide 9

Slide 9 text

Beneﬁts of good documentation to developers ✗ Improved developer experience (DevX) 9

Slide 10

Slide 10 text

Beneﬁts of good documentation to developers ✗ Improved developer experience (DevX) ✗ Help you achieve your growth goals 10

Slide 11

Slide 11 text

IF Documentation is so good, what are we still doing here? 11

Slide 12

Slide 12 text

Tooling 11

Slide 13

Slide 13 text

Tooling refers to all development tools/processes that make our code more maintainable and useable for others. 13

Slide 14

Slide 14 text

14 Examples of Tooling

Slide 15

Slide 15 text

15 Type-safe Code (Type-safety)

Slide 16

Slide 16 text

16 Using Type-safe code (Typescript) :)

Slide 17

Slide 17 text

17 Using Type-safe code (Typescript) :)

Slide 18

Slide 18 text

18 Using Type-safe code (Typescript) :)

Slide 19

Slide 19 text

Type unsafe (normal JavaScript) code won’t do this 19

Slide 20

Slide 20 text

20 Using type unsafe code (JavaScript) :(

Slide 21

Slide 21 text

21 Using type unsafe code (JavaScript) :(

Slide 22

Slide 22 text

22 Using type unsafe code (JavaScript) :(

Slide 23

Slide 23 text

23 Documentation Generators

Slide 24

Slide 24 text

Examples of Documentation generators ✗ JSDoc ✗ Python DocStrings ✗ Javadoc 24

Slide 25

Slide 25 text

JSDoc is a documentation generator for Javascript 25

Slide 26

Slide 26 text

26 Syntax:

Slide 27

Slide 27 text

27 Using JSDoc :)

Slide 28

Slide 28 text

28 Using JSDoc :)

Slide 29

Slide 29 text

29 Not using JSDoc :(

Slide 30

Slide 30 text

30 Not using JSDoc :(

Slide 31

Slide 31 text

Beneﬁt of tooling 31 Improved Developer Experience

Slide 32

Slide 32 text

When should you use these tooling? 32

Slide 33

Slide 33 text

Should you prefer one over the other? (documentation or tooling) 33

Slide 34

Slide 34 text

NO! 34

Slide 35

Slide 35 text

Key takeaway 35 As developers, managers, open-source maintainers we owe it to ourselves, to the community and to the developers who would use our code to incorporate documentation, best code practices and any other tools/process that will support them to use our code — That’s open source to me

Slide 36

Slide 36 text

Thank YOU! You can ﬁnd me at: @Victor_codejs 36 Link to slides — https://bit.ly/docs-vs-tooling