Lessons learned: Choosing your documentation system
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.
Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Similar to Lessons learned: Choosing your documentation system
Similar to Lessons learned: Choosing your documentation system (20)
More from Pronovix
More from Pronovix (20)
Recently uploaded
Recently uploaded (20)
Lessons learned: Choosing your documentation system
- 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
- 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
- 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