As developers we get often asked to write more, better and earlier documentation.

While it is very important and useful, to have the right documentation when needed and more often than not we are lacking important documentation, it is also important to avoid writing too much documentation.

This applies to all levels of documentation, including comments in the code (javadoc, scaladoc, rubydoc, perldoc,… as well as inline comments), design documentation, Wiki/Confluence, external documents.

Some projects measure the quantity of documentation, for example. Or the coverage of javadoc. And people start writing automatically generated or trivial comments on getters and setters. While there can be a comment documenting the attribute placed with the getter instead of the attribute itself, this is usually a bad idea, because it just clutters the code with no gain at all. Commenting should be limited to the non-obvious. And code should be written in such a way, that there is not more non-obvious than necessary. So code that is readable and understandable with few comments is actually a better goal.

For APIs we might want some more documentation. But we should keep it as close to the code as possible and use tools like swagger or scripts to create API-documentation from the code or code and documentation from the API-specification. This has a better chance of staying up to date, while hand maintained documentation always tends to get outdated over the time.

It is good to describe the overall working of the system. But details should be looked up in the code, where that is a viable option.

It is important to describe, how to get started. And even better, if getting started is easy because of automation, scripts or tools that do it in a few, relatively easy steps. This is a goal that everybody seems to have, but nobody seems to succeed with.

It is important to describe, how certain problems are solved in the team or have been solved, in terms of how it should be done to conform with other solutions or how it can successfully done. Guidelines are probably a good idea. Even better, if they can reference as much as possible well established guidelines published in the internet and just describe the exceptions or details about which the public guidelines do not make a decision, but that should be done coherently within the project.

And the business side of the software should of course be described also in documentation.

The agile manifesto recommends: „Working software over comprehensive documentation“.
But this should not stop us from writing documentation that really helps us.


Share Button

Word Documents vs. Wiki

It was this typical clash of cultures when a real IT guy, scientist, mathematician or engineer joined a company and suddenly an office package had to be used. It could have been any of them, think LibreOffice or MS-Office, but there were some others, that have meanwhile lost relevance. We liked to use text files or HTML or LaTeX or even Literate Programming, part of which has conceptionally made it into our time as JavaDoc and similar concepts for most modern languages. The idea is to keep source code and documentation together and in sync, to work with a similar technology stack for software and documentation and to be able to use typical Linux/Unix-tools like grep, Perl, Python or Ruby on the document files to search, to create them, to transform them, to parse them etc. Do not use awk and sed for these purpose any more, they have been superseded by scripting languages.

So now all tools for automatizing things and for working efficiently or at least comfortably where gone, maybe the office even forced us to use such a non-developer-system as MS-Windows for developing software that should eventually run on Linux– or Unix-Servers. Working together on the same file was a nightmare, in spite of the existence of some software that claims to support this. And yes, I know that these office packages contain scripting languages, like VBA or LibreOffice Basic that might not be our favorite, but could eventually be powerful if we took the effort and learned them. But actually the people who learned this were mostly on the „business side“ and sometimes they were faster getting a functionality up and running than we professionals. Up and running as long as their C:-drive was up and running…

So now after the anger is gone or hopefully at least a bit reduced, it is good to actually take a look. The „classical“ office suite contained a word processor, a spread sheet and a presentation program, other components like a database have become optional and I see them rarely in use.

I think that there is no serious doubt about wanting to have a spread sheet. And a presentation program is mostly useful as well, even though there are serious alternatives to be seen like doing presentations in modern HTML. The arguments against the word processor of typical office suites have proven to somewhat survive through all the years. While the word processor is useful for exchanging documents with people who are heavily working with them and cannot easily be taught otherwise, it has pretty much disappeared from our daily work. Since around 2008 the main documentation tool in the overwhelming majority of projects that I have seen was a private Wiki, like MediaWiki or Confluence or Redmine, for example.

This allowed for easier collaboration, it was a web application that worked with any modern browser and any OS and it was a bit more natural to use and somewhat easier to read and write and search. The Wikis do have a text format, that can be processed in situations where we want to generate documentation from code or code from documentation. And it could be more easily controlled than Word-documents, that were mailed around and changed.

Document management systems or enterprise content management systems allow us to do a lot of stuff even with „classical“ office files. I know that the more advanced systems are very powerful. But I have rarely seen it in the context of software development and architecture projects. So I am not going to write too much about them, but leave this area to the experts of this field.

Generally I find it much more pleasant to work with Wikis than it was before with Office-Documents, so I would consider this a positive development.

Share Button

Bring your own Device

This issue is quite controversial and it applies to laptops, tablets and smart phones.
Usually the „bringing“ is not really an issue, you can have anything in your bags and connect it via the mobile phone network as long as it does not absorb the working time.
But usually this implies a bit more.
There are some advantages in having company emails and calendar on a smart phone. This is convenient and useful. But there are some security concerns that should be taken serious. How is the calendar and the emails accessed? How confidential are the emails? Do they pass through servers that we do not trust? What happens, if a phone gets lost?
This is an area, where security concerns are often not taken too serious, because it is cool for top manager to have such devices. And they can just override any worries and concerns, if they like.
This can be compensated by being more restrictive in other areas. 😉
Anyway, the questions should be answered. In addition, the personal preferences for a certain type of phone are very strong. So the phone provided by the company might not be the one that the employee prefers, so there is a big desire to use the own phone or one that is similar to the own phone, which depends on the question of who pays the bills, how much of private telephony is allowed on the company phone and if there are work related calls to abusive times.
Generally the desirable path is to accept this and to find ways to make this secure.

The other issue is about the computer we work with. For some kind of jobs it is clear that the computer of the company is used, for example when selling railroad tickets or working in the post office or in a bank serving customers.

It shows that more creative people and more IT-oriented people like to have more control on the computer they work with.
We like to have hardware that is powerful enough to do the job. We like to be able to install software that helps us do our job. We like to use the OS and the software that we are skilled with. Sometimes it is already useful to be able to install this on the company computer or in a virtual computer within the company computer. Does the company allow this? It should, with some reasonable guidelines.

Some companies allow their employees to use their own laptops instead. They might give some money to pay for this and expect a certain level of equipment for that. Or just allow the employees to buy a laptop with their own money and use it instead of the company computer. They will do so and happily spend the money, even though it is wrong and the company should pay it. But the pain of spending some of the own money is for many people less than the pain of having to use crappy company equipment.

This rises the question of the network drive Q:, the outlook, MS-Word, MS-Excel,…
Actually this is not so much an issue, at least for the group we are talking here. Or becoming less of an issue.
Drive Q: can quite well be accessed from Linux, if the company policies allow it. But actually modern working patterns do not need this any more.
We can use a Wiki, like MediaWiki or Confluence for documentation. This is actually a bit better in many cases and I would see a trend in this direction, at least for IT-oriented teams.
Office-Formats and Email are more and more providing Web-Applications that can be used to work with them on Linux, for example. And MS-Office is already available for Linux, at least for Android, which is a Linux Variant. It might or might not come for Desktop Linux. LibreOffice is most of the time a useful replacement. Maybe better, maybe almost as good, depending on perspective… And there is always the possibility to have a virtual computer running MS-Windows for the absolutely mandatory MS-Windows-programs, if they actually exist. Such an image could be provided and maintained by the company instead of a company computer.

It is better to let the people work. To allow them to use useful tools. To pay them for bringing their own laptop or to allow them to install what they want on the company laptop. I have seen people who quit their job because of issues like this. The whole expensive MS-Windows-oriented universe that has been built in companies for a lot of money proves to be obsolete in some areas. A Wiki, a source code repository, … these things can be accessed over the internet using ssh or https. They can be hosted by third parties, if we trust the third party. Or they can be hosted by the company itself. Some companies work with distributed teams…

It is of course important to figure out a good security policy that allows working with „own“ devices and still provide a sufficient level of security. Maybe we just have to get used to other ways of working and to learn how to solve the problems that they bring us. In the end of the day we will see which companies are more successful. It depends on many factors, but the ability to provide a innovative and powerful IT and to have good people working there and actually getting stuff done is often an important factor.

Share Button

How to make a scanned PDF smaller (Linux)

When scanning a paper, it is possible to use a lot of parameters within xsane. The output format can be chosen also, for example PNG, JPG or PDF. The outcome may be a PDF-file that is way too big, easily more than 10 megabytes for a single page. It is quite easy to transform it to a smaller file:

convert -density 200x200 -quality 60 -compress jpeg \
big-scanned-file.pdf compressed-scanned-file.pdf

Unless you scan very often, it is easier to scan once with a relatively high resolution and then run this conversion with different values for quality and density rather than running the time consuming scan with different xsane settings.

Share Button