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

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

A thoughts of an old-school Java programmer while learning some iOS

..are not designed to be a fast-search-answer book. (search behaves bad actually). It's a tightly linked bundle of articles (with lots of html pop-up annotations!), which you have to read one after anohter. This creates a rich market of developers books, of course. But I'm not fan of overspending :-)

This stands in direct opposition to how Sun's Java docs were presented: to understand how to use library, one need to read only the class/interface descriptions (I can't remember I read package docs, anyone?); each class description is a very short and contains the concept of how it iteracts with others.

I think it comes from language differences: Java presents more plain classes without multi-file classes (.h, .m in ObjectiveC). So with proposed (by Sun?) javadoc inline style documentation Java classes are much easier to describe and support the changes.

Anyway, I spend more time to find information even in cases when I know what I'm looking for, comparing to Java SDK or ME docs or even Android docs.

For the Apple iOS docs, single place for navigating across whole bundle of articles could be very good.

Labels: docs, ios, java, programming

In new version of text editor of GDocs it's very hard to maintain aspect ratio of drawings to keep text readable. Drawing is rendered at server side and the aspect ratio of drawing when rendered in document now does not correlate with its content size. Renderer tries to calculate the text scale from drawing aspect ratio. But size is not correlated to drawing content. So anytime you insert or change drawing you have to manually adjust its size just to make text readable (which is very hard, because text is not rendered in a stylish way for any scale incompatibility).
It's impossible to use previous version of drawer with new version document, but you can create documents in old version of editor. Also, It's impossible to copy drawing from new version to old one via web clipboard.
In comparison to GDocs tricks MS Office is just as solid as stone. Just checked: 2007 Word has almost same cool drawings editor.
I need solution to simplify sharing of DOCs (svn seems to me very heavy for such an easy task, cause it's impossible to use web interface to share or publish one document). Do you know one?

Labels: docs, evil, google, ms, office2007, question