LETS GET YOUR DOCUMENTATION RIGHT ALL ABOUT ME DANIELE PROCIDA - - PowerPoint PPT Presentation

▶
let s get your documentation right
SMART_READER_LITE
LIVE PREVIEW

LETS GET YOUR DOCUMENTATION RIGHT ALL ABOUT ME DANIELE PROCIDA - - PowerPoint PPT Presentation

Mar 22, 2024 105 likes •589 views

DANIELE PROCIDA LETS GET YOUR DOCUMENTATION RIGHT ALL ABOUT ME DANIELE PROCIDA Divio (cloud hosting for Python/Django) Django core developer Board member, Django Software Foundation Python in Africa

slide-1
SLIDE 1

LET’S GET YOUR DOCUMENTATION RIGHT

DANIELE PROCIDA

slide-2
SLIDE 2

ALL ABOUT ME

DANIELE PROCIDA

▸ Divio (cloud hosting for Python/Django) ▸ Django core developer ▸ Board member, Django Software Foundation ▸ Python in Africa ▸ daniele.procida@divio.com ▸ EvilDMP (IRC, GitHub, Twitter) ▸ … or just talk to me!

slide-3
SLIDE 3

THERE ISN’T ONE THING CALLED “DOCUMENTATION”…

slide-4
SLIDE 4

…THERE ARE FOUR

slide-5
SLIDE 5
slide-6
SLIDE 6

EXPLANATION REFERENCE TUTORIALS HOW-TO GUIDES

slide-7
SLIDE 7

TUTORIALS

lessons that take the reader by the hand through a series of steps to complete a project

slide-8
SLIDE 8

TUTORIALS

WHAT MATTERS

▸ learning by doing ▸ getting started ▸ inspiring confidence ▸ repeatability ▸ immediate sense of achievement ▸ concreteness, not abstraction ▸ minimum necessary explanation ▸ no distractions

slide-9
SLIDE 9

HOW-TO GUIDES

guides that take the reader through the steps required to solve a common problem

slide-10
SLIDE 10

HOW-TO GUIDES

WHAT MATTERS

▸ a series of steps ▸ a focus on the goal ▸ addressing a specific question ▸ no unnecessary explanation ▸ a little flexibility ▸ practical usability ▸ good naming

slide-11
SLIDE 11

REFERENCE

technical descriptions of the machinery and its

  • peration
slide-12
SLIDE 12

REFERENCE

WHAT MATTERS

▸ structure ▸ consistency ▸ description ▸ accuracy

slide-13
SLIDE 13

EXPLANATION

discussions that clarify and illuminate a particular topic

slide-14
SLIDE 14

EXPLANATION

WHAT MATTERS

▸ giving context ▸ explaining why ▸ multiple examples, alternative approaches ▸ making connections ▸ no instruction or technical description

slide-15
SLIDE 15

EXPLANATION REFERENCE TUTORIALS HOW-TO GUIDES

LEARNING-ORIENTED PROBLEM-ORIENTED UNDERSTANDING-ORIENTED INFORMATION-ORIENTED

slide-16
SLIDE 16

EXPLANATION REFERENCE TUTORIALS HOW-TOS

L E A R N I N G

  • O

R I E N T E D PROBLEM-ORIENTED U N D E R S T A N D I N G

  • O

R I E N T E D INFORMATION-ORIENTED

slide-17
SLIDE 17

EXPLANATION REFERENCE TUTORIALS HOW-TO GUIDES

LEARNING-ORIENTED PROBLEM-ORIENTED UNDERSTANDING-ORIENTED INFORMATION-ORIENTED

slide-18
SLIDE 18

TUTORIALS HOW-TO GUIDES

Practical steps

slide-19
SLIDE 19

REFERENCE HOW-TO GUIDES

Most useful when we’re coding

slide-20
SLIDE 20

EXPLANATION REFERENCE

Theoretical knowledge

slide-21
SLIDE 21

EXPLANATION TUTORIALS

Most useful when we’re studying

slide-22
SLIDE 22

EXPLANATION REFERENCE TUTORIALS HOW-TOS

L E A R N I N G

  • O

R I E N T E D PROBLEM-ORIENTED U N D E R S T A N D I N G

  • O

R I E N T E D INFORMATION-ORIENTED

slide-23
SLIDE 23

Most useful when we’re coding Practical steps Theoretical knowledge Most useful when we’re studying

EXPLANATION REFERENCE TUTORIALS HOW-TO GUIDES

LEARNING-ORIENTED PROBLEM-ORIENTED UNDERSTANDING-ORIENTED INFORMATION-ORIENTED

slide-24
SLIDE 24
slide-25
SLIDE 25
slide-26
SLIDE 26
slide-27
SLIDE 27

Most useful when we’re coding Practical steps Theoretical knowledge Most useful when we’re studying

EXPLANATION REFERENCE TUTORIALS HOW-TO GUIDES

LEARNING-ORIENTED PROBLEM-ORIENTED UNDERSTANDING-ORIENTED INFORMATION-ORIENTED

slide-28
SLIDE 28

ANOTHER EXAMPLE

slide-29
SLIDE 29

TUTORIALS

LEARNING-ORIENTED LESSONS

slide-30
SLIDE 30
slide-31
SLIDE 31

HOW-TO GUIDES

PROBLEM-ORIENTED STEPS

slide-32
SLIDE 32
slide-33
SLIDE 33

REFERENCE

INFORMATION-ORIENTED TECHNICAL DESCRIPTION

slide-34
SLIDE 34
slide-35
SLIDE 35

EXPLANATION

UNDERSTANDING-ORIENTED DISCUSSION

slide-36
SLIDE 36
slide-37
SLIDE 37

Most useful when we’re coding Practical steps Theoretical knowledge Most useful when we’re studying

slide-38
SLIDE 38
slide-39
SLIDE 39

divio.com/blog/documentation

slide-40
SLIDE 40

EXERCISE

DOCUMENT THE GAME OF CHESS

slide-41
SLIDE 41

Introduction How to… Reference Explanation

slide-42
SLIDE 42

Introduction - your first game

  • 1. Set up the board
  • 2. Take each piece through its moves
  • 3. Capture a piece
  • 4. Check the King
  • 5. Checkmate - you win!

How to…

  • Open the game
  • Respond to common openings
  • Control the centre of the board
  • Use a chess clock

Reference

  • The rules of chess
  • Competition rules
  • Standard competition formats

Explanation

  • The history of chess
  • Middle-game strategies
  • End-game strategies
  • Numerical and positional advantage
slide-43
SLIDE 43

EXERCISE

LET’S DOCUMENT OUR SOFTWARE

Our API allows us to interrogate and manage all the data associated with a conference - people, presentations, tickets, schedule, etc. Your job: write the documentation.

slide-44
SLIDE 44

Introduction How to… Reference Explanation

slide-45
SLIDE 45

Introduction

  • 1. Install the client and demo server
  • 2. Authenticate
  • 3. Read data
  • 4. Construct a complex query
  • 5. Write data

How to…

  • Embed the client in an application
  • Authenticate using LDAP
  • Lock the database for complex writes
  • Use query batching
  • Use an alternative client

Reference

  • Client commands and options
  • Data schema format
  • API query language
  • The authentication system
  • Error codes

Explanation

  • When not to use the API
  • Batching vs caching
  • Designing complex queries
  • Performance-optimisation strategies
  • Working with large databases
slide-46
SLIDE 46

TALK TO ME

DANIELE PROCIDA

▸ Divio ▸ Django ▸ dockerised Django deployment ▸ documentation ▸ daniele.procida@divio.com ▸ EvilDMP (IRC, GitHub, Twitter)

slide-47
SLIDE 47

divio.com/blog/documentation