Shamil's Blog. Software Engineering Processes, Android, CI, Devops.

For a plantuml nice and simple diagrams text generation tool integration with the gitlab server setup, the plantuml server needs to be exposed to external network. Which is not good. Although some of security risks can be mitigated with running plantuml in docker but definitely not all (such as data exposure, DoS attacks) and mitigating them requires lots of careful manual tuning. Gitlab needs plantuml integration to host rendered images on its side. Maybe aa a plugin. I definitely want to investigate this.

Labels: devops, diagram, docker, git, gitlab, plantuml, security, uml, work process

Recently I don't see almost any diagrams in software docs. It seems like the nowadays developers cannot also create any ascii-graphics like this BufferStrategy class doc written 10+ years ago. None of such I've seen in Android docs (point me out to any please?).

Moreover some talented developers seems don't want to document at all. Check out this one, very complex UI behaviour class AppBarLayout.Behavior. It says: "The default AppBarLayout.Behavior for AppBarLayout. Implements the necessary nested scroll handling with offsetting." That's all. What exactly is necessary?

Yes, I've heard many times that mantra of idlers "code source is the best documentation for itself". Without docs it requires sometimes hours or even days to know all the nuances of implementation. In total it requires additional man*years if some popular framework is poorly documented and decreases overall experience of developers and users for using such piece of technology.

So my friend, let's start documenting the sources we write with something more than the usual "f%ck off I'm busy"-style docs and comments that we see in so many docs by adding the details of implementation and side effects. And diagrams!

Labels: android, API, computer science, diagram, docs, documentation, framework, programming