I'm Principal Software Engineer at Swimm. A startup building a documentation tool for developers based on the paradigms of Continuous Documentation.
What is continuous documentation
"Continuous documentation is the process of creating and updating documentation incrementally and as part of the development workflow, ensuring it is in sync with the codebase."
The author - who happens to be a good friend of mine - argue for 3 main principles.
Continuous Documentation means that the documentation is:
- Code-coupled
- Always up-to-date
- Created when best
Sounds good in theory, right?
But how does it work in practice?
One way is through Git Checks
Swimm automatically checks any documentation pushed to git to make sure it’s up to date. If the code mentioned in your documentation changed, Swimm alerts you and lets you address the issue quickly and easily. This way both your code and your documentation are always accurate and up to date.
I invite you to check out Swimm and join our free open beta and I'm happy to chat with anyone from the dev.to community to show them the various use cases for Swimm - for both teams and individuals.
Top comments (4)
Nice idea!
For me the problem with the documentation si too keep it updated. I mean, sometimes we're coding and when we're arriving to the last part of our tasks is hard to remember all the things that we made, well, we can put an extra complication here, imagine this a subtask of an story that are assigned for three developers, this is getting complicated right? how we will organise all the documentation, and what is the best way to document it?
When we're learning software development nobody is showing to us methodologies for document well. This is probably one of the big mistakes, because we don't have the habit.
For me the best documentation is the code and the tests that we're applying in the code. An idea that I had in my mind is to apply an extra step in TDD (is my way to work) and writing the documentation before starts to code but the problem here is when we're changing our "roadmap" after writing or updating the documentation.
In the end document the code is not an easy work and not all the people have the skills to do it.
Keeping docs up to date is exactly the problem we've solving. Our tool will automatically update or let you know when your documentation needs review.
Agree that a lack of methodologies is a hindrance - we actually have a template library to get you started and to suggest what to include.
For lib developer/maintainer, documentation coverage is more important than code coverage. Do you have some sort of metrics to check if lib/package is properly documented?
We allow you to set coverage goals for each repo and then track the progress.