SlideShare a Scribd company logo
1 of 36
Download to read offline
$ cod == doc
$ Why now?
Remote
Async worker
Scalable
Independence
$ What we need for coding
Write
Read
IDE SCM
Share
Review
Historicize
Language
Scala
Ruby
Gerrit
Git
Source graph
Search
$ What we need for documenting
Write
Read
IDE SCM
Share
Review
Historicize
Language
Confluence
Markdown
Diagram English
Search
$ Code IDE vs Doc IDE
Code Doc
$ Code log VS Doc log
Doc
Code
$ Code diff VS Doc diff
Doc
Code
$ Code review VS Doc review
Code Doc
$ Code search VS Doc search
Code Doc
$ Code challenges vs Doc challenges
Performance Readable Maintainable Factorization Decentralization Design
Code ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Documentation ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
$ Code is a type of documentation
“Code is self documenting”
$ Code is not sufficient
Code is not sufficient to document a project:
• Implicit relation with the infrastructure (ex: at runtime)
• Don’t offer a high-level view (ex: brainstorm)
• Cannot describe its own expected behavior (ex: bug)
$ Documentation for a project
Deployment
Specification
Runtime
Implementation documentation
code, dependency, test …
architecture, behavior, usage, API, SLA …
dependency, monitoring, resources, data
CI/CD, artifact, config
$ Different generations of documentations
Documentation
Manual
Partiallygenerated
Fully generated
on-demand
systematic
Code/data itself (ex: protobuf)
Fromcode/data (ex: swagger, javadoc, testreport)
Fromcode/data (ex: datadoc, template) Code/data itself
Specification (ex: architecture…)
$ Criteo documentation
“Talk is cheap, show me the doc”
$ Criteo documentation
Our documentation How it could be
$ Criteo documentation
The Criteo documentation could better organized:
• Raise awareness and train the Criteo employees
• Maintain and clean our documentations
• Standardize our documentationswith a common culture
• Value the people that documents
• Develop/use tools to reduce the manual documentation
$ A lot of tools for documentation @Criteo
Perpetuo
Jenkins/Gradle
Datadoc
Evergreen
SwaggerCatalog
Grafana
Confluence JIRA
IntelliJ
Gerrit
# Documentation is missing
“Everyone wants to have documentation,
but nobody wants to produce it”
# What is documentation paradigm?
“It is harder to read code than to write it”
“It is harder to write doc than to read it”
# Find the right cursor
Under-documenting
vs
Over-documenting
# Segment your documentation
Human organization
Contributors
Developers
End-Users
# Required documentation
Design
Data
# Golden rules
1. Fit for context
2. Clearly written
3. Visual where possible
4. Structured
5. Up to date
6. Discoverable & Tracked
7. Reviewed
# Several layers of understanding
High level
Low level
Code/Data
Architecture/Design
Documentation
# Documentation for everyone
“Ink is better than memory”
# How to become an expert
“An expert resolves continuously new challenges,
and document those that are resolved”
$ Questions
$ Audience survey
https://forms.microsoft.com/r/DgpsaG0Mt7
$ Time for beers

More Related Content

Similar to Beer&Tech: Tech Documentation - cod == doc

Devopsdays State of the Union Amsterdam 2014
Devopsdays State of the Union Amsterdam 2014 Devopsdays State of the Union Amsterdam 2014
Devopsdays State of the Union Amsterdam 2014
John Willis
 
Class 6: Introduction to web technology entrepreneurship
Class 6: Introduction to web technology entrepreneurshipClass 6: Introduction to web technology entrepreneurship
Class 6: Introduction to web technology entrepreneurship
allanchao
 

Similar to Beer&Tech: Tech Documentation - cod == doc (20)

"Different software evolutions from Start till Release in PHP product" Oleksa...
"Different software evolutions from Start till Release in PHP product" Oleksa..."Different software evolutions from Start till Release in PHP product" Oleksa...
"Different software evolutions from Start till Release in PHP product" Oleksa...
 
PHPFrameworkDay 2020 - Different software evolutions from Start till Release ...
PHPFrameworkDay 2020 - Different software evolutions from Start till Release ...PHPFrameworkDay 2020 - Different software evolutions from Start till Release ...
PHPFrameworkDay 2020 - Different software evolutions from Start till Release ...
 
Which Questions We Should Have
Which Questions We Should HaveWhich Questions We Should Have
Which Questions We Should Have
 
Andrea Di Persio
Andrea Di PersioAndrea Di Persio
Andrea Di Persio
 
13 practical tips for writing secure golang applications
13 practical tips for writing secure golang applications13 practical tips for writing secure golang applications
13 practical tips for writing secure golang applications
 
Devopsdays State of the Union Amsterdam 2014
Devopsdays State of the Union Amsterdam 2014 Devopsdays State of the Union Amsterdam 2014
Devopsdays State of the Union Amsterdam 2014
 
Measuring Your Code
Measuring Your CodeMeasuring Your Code
Measuring Your Code
 
Measuring Your Code 2.0
Measuring Your Code 2.0Measuring Your Code 2.0
Measuring Your Code 2.0
 
Microservices as an evolutionary architecture: lessons learned
Microservices as an evolutionary architecture: lessons learnedMicroservices as an evolutionary architecture: lessons learned
Microservices as an evolutionary architecture: lessons learned
 
Hire Backend Developer for your project!
Hire Backend Developer for your project!Hire Backend Developer for your project!
Hire Backend Developer for your project!
 
Azure doc db (slideshare)
Azure doc db (slideshare)Azure doc db (slideshare)
Azure doc db (slideshare)
 
It is a sunny day
It is a sunny dayIt is a sunny day
It is a sunny day
 
Friday final test
Friday final testFriday final test
Friday final test
 
Simplifying & accelerating application development with MongoDB's intelligent...
Simplifying & accelerating application development with MongoDB's intelligent...Simplifying & accelerating application development with MongoDB's intelligent...
Simplifying & accelerating application development with MongoDB's intelligent...
 
[PASS Summit 2016] Blazing Fast, Planet-Scale Customer Scenarios with Azure D...
[PASS Summit 2016] Blazing Fast, Planet-Scale Customer Scenarios with Azure D...[PASS Summit 2016] Blazing Fast, Planet-Scale Customer Scenarios with Azure D...
[PASS Summit 2016] Blazing Fast, Planet-Scale Customer Scenarios with Azure D...
 
Enterprise Data Workflows with Cascading and Windows Azure HDInsight
Enterprise Data Workflows with Cascading and Windows Azure HDInsightEnterprise Data Workflows with Cascading and Windows Azure HDInsight
Enterprise Data Workflows with Cascading and Windows Azure HDInsight
 
Class 6: Introduction to web technology entrepreneurship
Class 6: Introduction to web technology entrepreneurshipClass 6: Introduction to web technology entrepreneurship
Class 6: Introduction to web technology entrepreneurship
 
Angular mobile angular_u
Angular mobile angular_uAngular mobile angular_u
Angular mobile angular_u
 
gRPC, GraphQL, REST - Which API Tech to use - API Conference Berlin oct 20
gRPC, GraphQL, REST - Which API Tech to use - API Conference Berlin oct 20gRPC, GraphQL, REST - Which API Tech to use - API Conference Berlin oct 20
gRPC, GraphQL, REST - Which API Tech to use - API Conference Berlin oct 20
 
Embarcadero's Connected Development
Embarcadero's Connected DevelopmentEmbarcadero's Connected Development
Embarcadero's Connected Development
 

Recently uploaded

Seizure stage detection of epileptic seizure using convolutional neural networks
Seizure stage detection of epileptic seizure using convolutional neural networksSeizure stage detection of epileptic seizure using convolutional neural networks
Seizure stage detection of epileptic seizure using convolutional neural networks
IJECEIAES
 
21P35A0312 Internship eccccccReport.docx
21P35A0312 Internship eccccccReport.docx21P35A0312 Internship eccccccReport.docx
21P35A0312 Internship eccccccReport.docx
rahulmanepalli02
 
Artificial intelligence presentation2-171219131633.pdf
Artificial intelligence presentation2-171219131633.pdfArtificial intelligence presentation2-171219131633.pdf
Artificial intelligence presentation2-171219131633.pdf
Kira Dess
 
Final DBMS Manual (2).pdf final lab manual
Final DBMS Manual (2).pdf final lab manualFinal DBMS Manual (2).pdf final lab manual
Final DBMS Manual (2).pdf final lab manual
BalamuruganV28
 

Recently uploaded (20)

Insurance management system project report.pdf
Insurance management system project report.pdfInsurance management system project report.pdf
Insurance management system project report.pdf
 
Seizure stage detection of epileptic seizure using convolutional neural networks
Seizure stage detection of epileptic seizure using convolutional neural networksSeizure stage detection of epileptic seizure using convolutional neural networks
Seizure stage detection of epileptic seizure using convolutional neural networks
 
analog-vs-digital-communication (concept of analog and digital).pptx
analog-vs-digital-communication (concept of analog and digital).pptxanalog-vs-digital-communication (concept of analog and digital).pptx
analog-vs-digital-communication (concept of analog and digital).pptx
 
Autodesk Construction Cloud (Autodesk Build).pptx
Autodesk Construction Cloud (Autodesk Build).pptxAutodesk Construction Cloud (Autodesk Build).pptx
Autodesk Construction Cloud (Autodesk Build).pptx
 
Worksharing and 3D Modeling with Revit.pptx
Worksharing and 3D Modeling with Revit.pptxWorksharing and 3D Modeling with Revit.pptx
Worksharing and 3D Modeling with Revit.pptx
 
Fuzzy logic method-based stress detector with blood pressure and body tempera...
Fuzzy logic method-based stress detector with blood pressure and body tempera...Fuzzy logic method-based stress detector with blood pressure and body tempera...
Fuzzy logic method-based stress detector with blood pressure and body tempera...
 
Artificial Intelligence in due diligence
Artificial Intelligence in due diligenceArtificial Intelligence in due diligence
Artificial Intelligence in due diligence
 
CLOUD COMPUTING SERVICES - Cloud Reference Modal
CLOUD COMPUTING SERVICES - Cloud Reference ModalCLOUD COMPUTING SERVICES - Cloud Reference Modal
CLOUD COMPUTING SERVICES - Cloud Reference Modal
 
NEWLETTER FRANCE HELICES/ SDS SURFACE DRIVES - MAY 2024
NEWLETTER FRANCE HELICES/ SDS SURFACE DRIVES - MAY 2024NEWLETTER FRANCE HELICES/ SDS SURFACE DRIVES - MAY 2024
NEWLETTER FRANCE HELICES/ SDS SURFACE DRIVES - MAY 2024
 
Adsorption (mass transfer operations 2) ppt
Adsorption (mass transfer operations 2) pptAdsorption (mass transfer operations 2) ppt
Adsorption (mass transfer operations 2) ppt
 
UNIT 4 PTRP final Convergence in probability.pptx
UNIT 4 PTRP final Convergence in probability.pptxUNIT 4 PTRP final Convergence in probability.pptx
UNIT 4 PTRP final Convergence in probability.pptx
 
SLIDESHARE PPT-DECISION MAKING METHODS.pptx
SLIDESHARE PPT-DECISION MAKING METHODS.pptxSLIDESHARE PPT-DECISION MAKING METHODS.pptx
SLIDESHARE PPT-DECISION MAKING METHODS.pptx
 
Raashid final report on Embedded Systems
Raashid final report on Embedded SystemsRaashid final report on Embedded Systems
Raashid final report on Embedded Systems
 
Augmented Reality (AR) with Augin Software.pptx
Augmented Reality (AR) with Augin Software.pptxAugmented Reality (AR) with Augin Software.pptx
Augmented Reality (AR) with Augin Software.pptx
 
15-Minute City: A Completely New Horizon
15-Minute City: A Completely New Horizon15-Minute City: A Completely New Horizon
15-Minute City: A Completely New Horizon
 
21P35A0312 Internship eccccccReport.docx
21P35A0312 Internship eccccccReport.docx21P35A0312 Internship eccccccReport.docx
21P35A0312 Internship eccccccReport.docx
 
Artificial intelligence presentation2-171219131633.pdf
Artificial intelligence presentation2-171219131633.pdfArtificial intelligence presentation2-171219131633.pdf
Artificial intelligence presentation2-171219131633.pdf
 
Final DBMS Manual (2).pdf final lab manual
Final DBMS Manual (2).pdf final lab manualFinal DBMS Manual (2).pdf final lab manual
Final DBMS Manual (2).pdf final lab manual
 
The Entity-Relationship Model(ER Diagram).pptx
The Entity-Relationship Model(ER Diagram).pptxThe Entity-Relationship Model(ER Diagram).pptx
The Entity-Relationship Model(ER Diagram).pptx
 
UNIT-2 image enhancement.pdf Image Processing Unit 2 AKTU
UNIT-2 image enhancement.pdf Image Processing Unit 2 AKTUUNIT-2 image enhancement.pdf Image Processing Unit 2 AKTU
UNIT-2 image enhancement.pdf Image Processing Unit 2 AKTU
 

Beer&Tech: Tech Documentation - cod == doc

  • 1.
  • 2.
  • 3. $ cod == doc
  • 4. $ Why now? Remote Async worker Scalable Independence
  • 5.
  • 6.
  • 7. $ What we need for coding Write Read IDE SCM Share Review Historicize Language Scala Ruby Gerrit Git Source graph Search
  • 8. $ What we need for documenting Write Read IDE SCM Share Review Historicize Language Confluence Markdown Diagram English Search
  • 9. $ Code IDE vs Doc IDE Code Doc
  • 10. $ Code log VS Doc log Doc Code
  • 11. $ Code diff VS Doc diff Doc Code
  • 12. $ Code review VS Doc review Code Doc
  • 13. $ Code search VS Doc search Code Doc
  • 14. $ Code challenges vs Doc challenges Performance Readable Maintainable Factorization Decentralization Design Code ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ Documentation ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
  • 15. $ Code is a type of documentation “Code is self documenting”
  • 16. $ Code is not sufficient Code is not sufficient to document a project: • Implicit relation with the infrastructure (ex: at runtime) • Don’t offer a high-level view (ex: brainstorm) • Cannot describe its own expected behavior (ex: bug)
  • 17. $ Documentation for a project Deployment Specification Runtime Implementation documentation code, dependency, test … architecture, behavior, usage, API, SLA … dependency, monitoring, resources, data CI/CD, artifact, config
  • 18. $ Different generations of documentations Documentation Manual Partiallygenerated Fully generated on-demand systematic Code/data itself (ex: protobuf) Fromcode/data (ex: swagger, javadoc, testreport) Fromcode/data (ex: datadoc, template) Code/data itself Specification (ex: architecture…)
  • 19.
  • 20. $ Criteo documentation “Talk is cheap, show me the doc”
  • 21. $ Criteo documentation Our documentation How it could be
  • 22. $ Criteo documentation The Criteo documentation could better organized: • Raise awareness and train the Criteo employees • Maintain and clean our documentations • Standardize our documentationswith a common culture • Value the people that documents • Develop/use tools to reduce the manual documentation
  • 23. $ A lot of tools for documentation @Criteo Perpetuo Jenkins/Gradle Datadoc Evergreen SwaggerCatalog Grafana Confluence JIRA IntelliJ Gerrit
  • 24. # Documentation is missing “Everyone wants to have documentation, but nobody wants to produce it”
  • 25.
  • 26. # What is documentation paradigm? “It is harder to read code than to write it” “It is harder to write doc than to read it”
  • 27. # Find the right cursor Under-documenting vs Over-documenting
  • 28. # Segment your documentation Human organization Contributors Developers End-Users
  • 30. # Golden rules 1. Fit for context 2. Clearly written 3. Visual where possible 4. Structured 5. Up to date 6. Discoverable & Tracked 7. Reviewed
  • 31. # Several layers of understanding High level Low level Code/Data Architecture/Design Documentation
  • 32. # Documentation for everyone “Ink is better than memory”
  • 33. # How to become an expert “An expert resolves continuously new challenges, and document those that are resolved”
  • 36. $ Time for beers