There’s a confluence for the project from stone age I am helping out. Its aim is to provide the documentation for the project. Unfortunately, it does not have a clear focus for whom it is written.
Yep, a documentation has an audience - the stakeholders. Depending on the audience, it contains slightly different information, e.g. third-party devs connecting to the system want to know how to do just that and how they can map their business use cases to the systems API; on the other hand, the internal devs are probably not interested in such details as they care for their business use cases. Same goes when the audience is non-dev too.
Sandeep joins the discussion and comes up with a question regarding out-of-date documentation.
Yesterday’s topic and Alejandro’s reply lead me to another type of documentation. The out-of-code docs. Everything we document about our system which is not in the code or at least close to the code, that can be diagrams, wikis, word docs, whatever.
Yesterday I talked about a case of Javadoc gone wrong. Reader Alejandro wrote in and thinks I am missing the main problem here because it is the code and not the Javadoc. I’d like to discuss that a bit further.
Today I am presenting you a case of Javadoc gone wrong; an actual live one, just saw it today, live and in color, in the project from the stone age.
I know, many people do hate Mondays. Personally, I did too. But now, it’s the opposite. I love them.
One topic I’ve never found a perfect solution for is “how to document the architecture?”.
I’ve recently started a Spring Boot local meetup here in Frankfurt. We already had a great start with a talk about “Moving from Java to Kotlin with Spring Boot”. It was great to get first-hand experience from devs who already work with the Kotlin-Spring Boot combination.
DRY is another principle and commonly riding along the other two. DRY stands for don’t repeat yourself; meaning “Every piece of knowledge must have a single, unambiguous, authoritative representation within a system” aka writing that piece of code, schema, whatever once for the entire system and re-use. Don’t duplicate code if it’s logically related.
Another true principle of our craft is YAGNI - You ain’t gonna need it.