This document discusses code documentation and project documentation. It addresses the needs, tools, and challenges for both coding and documenting. Some key points made are: - Code and documentation have different needs for writing, reading, reviewing, etc. - Tools used for code like Git differ from those for documentation like Confluence. - Documentation is important but often neglected; it needs to be organized, standardized, discoverable, and maintained over time. - Different types of documentation are needed for specifications, deployments, runtimes, implementations, architectures and more. - Documentation needs to be tailored for different audiences like end users, developers, and contributors.

3. $ cod == doc

4. $ Why now?
Remote
Async worker
Scalable
Independence

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…)

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”

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

29. # Required documentation
Design
Data

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”

34. $ Questions

35. $ Audience survey
https://forms.microsoft.com/r/DgpsaG0Mt7

36. $ Time for beers