My team faced several questions a year ago when we started our brand new documentation portal. - Are we going to set up a platform based on an existing solution? - Are we going to create our own platform? - Are we going to use existing internal tools like Confluence? To answer those questions we created our own process to guide our decision making: - First create a vision how your documentation should look like - Then test as many platforms as possible - Realize non are quite what you want - Realise you do not want to reinvent the wheel - Figure out how you can glue different solution together to get exactly what you want We ended up with a mix of existing technologies like Doxygen and Sphinx, glued together with custom python scripts. This allowed us to rely on proven technology and still have the flexibility to tweak the result to our requirements, getting the best of both worlds. The biggest benefit of our solution is that it uses Unit tests to ensure that the documentation and the API stay in sync and developers are forced to update documentation when they change the API. This was one of the biggest benefits we gained from our new documentation system compared to the previously used. In this talk I will go into detail how we created and implemented our process, how it worked out for us and why your team might want to follow a similar process. At the end of the talk you will have a better understanding of - How to do research and compare documentation platforms - How to perform an informed decision for their documentation needs - How not quite reinvent the wheel and get what you want.

2. Bio
• Developing games for more than 15 years , 8 of those professionally
• Published textbook about Open Source Render Engine
• Worked for Unity
• Now working for King

3. The product
• Internal technology used to develop our games
• Team of around 40 people
• 1 Tech Writer
• 3 Advocates
• Around 800 users
• 400 developers
• API is not documented at all, some exceptions
• Most documentation in in Confluence
• And mostly outdated
• Push to improve API documentation to reduce support effort

4. Where to start?

5. Requirements
• Documentation needs to be next in code
• Ideally in the source files
• Each method should have its own page
• Code samples to show usage
• Ideally part of a test suite to stay up to date
• Able to display different versions of the API
• Using CSS for styling

6. Warning
• Based on personal research, might be missing some features
• An illustration how I approach this

7. Doxygen

8. Doxygen

9. Doxygen
• What is great
• Great C++ parsing support
• Simple to setup
• Default result is useful
• Well known
• What is not so great?
• Biggest issue is versioning control
• Takes a lot of space, can templated with HTML
• but not easy, at least for me
• Less options to customize

10. Read the Docs

11. Read the Docs
• What is great
• Default look and feel is great
• Support versioning
• Comes with a hosted services if needed
• Can be styled well
• What is not so great?
• No direct support for C++
• I had some issues getting versioning working

12. Breath

13. Breath
• What is great
• Used doxygen to parse C++
• Simple to setup
• Enables usage of ReadTheDocs
• What is not so great?
• Hard to modify result
• Takes a long time
• Personally I am not a fan of the aesthetics of the result

14. Web API

15. Web API
• What is great
• Widly used systems
• Easy to setup and update
• What is missing?
• Not meant for C++ code
• completely different ecosystem

16. Does not match anything
• After looking at all the solution
• Each one had some strong points
• But none ticked all the must haved we had

17. Doing it yourself

18. Doing it yourself
• Parsing C++

19. Doing it yourself
• Parsing C++

20. Doing it yourself
• Parsing C++
• Creating your own custom HTML

21. Doing it yourself
• Parsing C++
• Creating your own custom HTML

22. Doing it yourself
• Parsing C++
• Creating your own custom HTML
• Modifying already generated HTML

23. Doing it yourself
• Parsing C++
• Creating your own custom HTML
• Modifying already generated HTML

24. Doing it yourself
• Parsing C++
• Creating your own custom HTML
• Modifying already generated HTML
Doing it ourselves not a good idea either.

25. Finding a path forward

26. Finding a path forward

27. Finding a path forward

28. Doxygen
• Simple format to parse, but has its tricky areas
• Different files for classes and namespaces
• Can take a long while to run on big projects

29. Finding a path forward

30. Finding a path forward

31. Sphinx
• Uses RestructedText to generate HTML
• Easy to provide templates and CSS
• Can be extened using Python

32. Finding a path forward

33. Finding a path forward
Custom

34. Finding a path forward

35. Finding a path forward

36. Jinja2
• Simple templating engine in python
• Very powerful as it supports python in templates
• Takes a bit getting used to, to find best way to use it

37. Python glue code
• Still not completely done
• Can be a bit messy
• Requires a lot of test to ensure it stays correct

38. End result
• C++ to HTML with a lot of possibilities to customize
• All automated on Jenkins Build Server
• Integrated with GitHub to preview changes

39. • C++ to HTML with a lot of possibilities to customize
• All automated on Jenkins Build Server
• Integrated with GitHub to preview changes

40. Process to find your documentation portal
• Make a list of
• Must haves
• Nice to haves
• Dreams
• Spend enough time to learn about existing solutions
• Use each one a bit to get a feeling
• Then compare to your list
• If no ideal match, evaluate
• Time and resources for custom solution
• 80% of the list might be good enough

41. What to keep in mind
• Create a list of requirements and nice to haves
• First checkout existing solutions
• If nothing fits
• How much can be reused
• What can you do yourself
• Final decision