Slides from session during TYPO3 camp Berlin 2019 about TYPO3 documentation contribution

1. DOCUMENTATION
Sybille Peters
sybille.peters@typo3.org
@T3DocTeam
@sypets
TYPO3 Camp Berlin 2019
#t3cb

2. 1. Documentation
Team
2. Who writes
documentation?
3. What is TYPO3
documentation?
4. Structure
5. Contribution – Who,
how, why?
AGENDA
2

3. DOCUMENTATION
TEAM
3

4. DOCUMENTATION TEAM
 Martin Bless
 Daniel Siepmann
 Sybille Peters
4
25.06.2019 Sybille Peters
https://typo3.org/community/teams
/documentation

5. DOCUMENTATION TEAM
 Slack: #typo3-documentation
 Twitter: @T3DocTeam
 (Email: documentation@typo3.org)
5
25.06.2019 Sybille Peters
https://typo3.org/community/teams
/documentation

6. DOCUMENTATION TEAM: TASKS (1)
 Technical Infrastruktur:
– Docker Image
– Theme
– ...
6
25.06.2019 Sybille Peters

7. DOCUMENTATION TEAM: TASKS (2)
 „Writing Documentation“
 Merge PR
 Support: Slack channel #typo3-
documentation
 News, Twitter
 Slack calls, Sprints
7
25.06.2019 Sybille Peters

8. WHO WRITES
DOCUMENTATION
?
8

9. ?
9

10. TYPO3
COMMUNITY!
10

11. WHO WRITES DOCUMENTATION?
11
25.06.2019 Sybille Peters

12. WHO WRITES DOCUMENTATION?
In the past:
 Documentation Team
Today:
 Core Contributor: Changelog
 Core Team updates TYPO3 Explained, References etc.
 Community …
Everyone can contribute!
12
25.06.2019 Sybille Peters

13. WHAT IS TYPO3
DOCUMENTATION?
13

14. WHAT IS TYPO3 DOCUMENTATION?
 https://docs.typo3.org
 Official documentation / community
documentation
14

15. WHAT IS TYPO3 DOCUMENTATION?
Official Docs:
 Tutorials
 Guides
 References
 Changelog
 System Extension
 ...
15

16. WHAT IS TYPO3 DOCUMENTATION?
Community Docs:
 Third party
extension
documentation
16

17. WHAT IS TYPO3 DOCUMENTATION?
 Consistent format: reStructuredText
 Consistent structure
 Automatic Rendering (Webhook,
Intercept)
 Consistent Layout
17

18. TYPO3
DOCUMENTATION
IS
OPEN SOURCE!
18

19. HOW IS TYPO3
DOCUMENTATION
STRUCTURED?
19

20. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
 1x Homepage („glue pages)
 Manuals (Tutorials, Guides, etc.)
20

21. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
 1 manual → 1 GitHub repository
21
https://github.com/TYPO3-Documentationhttps://docs.typo3.org/m/typo3/reference-tca/master/en-us/

22. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
.
├── composer.json
└── Documentation
├── Index.rst
├── Settings.cfg
└── ...
22

23. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
23
 .rst : reStructuredText
 Text with markup
 Texteditor, IDE
 ReStructuredText plugin PhpStorm

24. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
24
DocTitle
└── Topic 1
└── Subtopic 1.1
└── Subtopic 1.1.1
└── Topic 2

25. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
25

26. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
About reStructuredText
 Writing Documentation
→ Common Pitfalls
→ Cheat Sheet
26

27. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
What about Markdown?
 Is supported
 Official documentation: reST
 Writing Documentation
→ Conventions → Formats
27
https://docs.typo3.org/m/typo3/docs-how-t
o-document/master/en-us/GeneralConve
ntions/Format.html

28. HOW IS TYPO3 DOCUMENTATION STRUCTURED?
What about Markdown?

28
https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/GeneralConventions/DirectoryFilenames.html

29. CONTRIBUTE
WHY?
29

30. ?
30

31. CONTRIBUTE – WHY?
 Is documentation up to date?
 How helpful is it?
31

32. TYPO3 NEEDS
GOOD
DOCUMENTATION
32

33. CONTRIBUTE – WHY?
Benefits of good documentation:
 Learning TYPO3 takes less time
 Easier onboarding for new employees
 More TYPO3 developer
 Less frustration
33

34. CONTRIBUTE – WHY?
Benefits of Contribution
 Better Documentation for everyone
 Learn (git, reST, GitHub, Docker,
write, explain)
34

35. CONTRIBUTE – WARUM?
35
COMMUNITYCOMMUNITY

36. CONTRIBUTE
WHAT?
36

37. ?
37

38. CONTRIBUTE – WHAT?
 Read!
 Feedback!
 Improve!
38

39. CONTRIBUTE – WHAT?
Was ist better?
 Write GitHub Issue?
 Or solve problem directly?
39

40. A SOLVED
PROBLEM IS ONE
LESS PROBLEM
40

41. CONTRIBUTE – WHAT?
Feedback
 Error / Problem → write Issue
 Slack Channel #typo3-
documentation
 Twitter: @T3DocTeam
41

42. CONTRIBUTE – WAS?
GitHub Issues
 Every manual has issues
 → Related Links → Issues
42https://github.com/TYPO3-Documentation

43. CONTRIBUTE – WHAT?
General Problems
 In Slack #typo3-documentation
 In Team repo:
https://github.com/TYPO3-Document
ation/T3DocTeam/issues
43

44. CONTRIBUTE – WHAT?
 More: „Writing Documentation“ →
„How You Can Help“
44

45. CONTRIBUTE
JUST START
45

46. CONTRIBUTE - START
 TYPO3 Blog:
 Writing
Documentation:


46

47. DEMO ...
47

48. THANK YOU!
48