Lessons learned: Choosing your documentation system
Felix Kerger is an experienced developer advocate with more than 16 years of experience in programming. He is currently working for King, a leading mobile game developer, leading the developer relations team for King’s internal game engine. Prior, Felix worked for Unity as an Enterprise Support engineer in Europe, and before that, he was an indie game developer. He also published a textbook about an open-source render engine and talked at different conferences about software development and, more specifically, game development.
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.