Intuition is better than manual?

In more than 25 years of working with software I have passed through various stages of using software. I was struggling with bad books, close to empty help files. I stumbled upon parts of interface, guessing what is logic behind, why workflow for some operations and procedures is not obvious. I could not do even simple things since books were scarce and expensive.

Translators who translated manuals and various technical books often invented new terminology and sometimes used awkward sentences in order to translate quite technical text on language which does not have those words in vocabulary. Some linguists were horrified with new intrusion of foreign languages and often coined their own  terms based on a lack of knowledge about technology concerned, misinterpretation of concepts and meaning.

Writing style was often very modest at least. There were no typographic differences between narrative text and command lines, illustrations too general and not representing the process described in paragraph.  Instructions were written in a way that can understand only those who already know that software. Those who did not know to use that software were mostly lost.  Procedures were not described concisely, some steps missing and above all, some examples were not workable.

On the other side, we have to be honest and confess that at the time, despite the fact that more than 20 years passed after wider using of operating systems and the development of software,  the software technology was at the beginning of introduction to the wider user population.  The code for Apollo mission was written by hand. Image bellow taken from Wikipedia shows Margaret Hamilton next to a stack of code she and her team wrote for the Apollo Mission computers.

software developer with books with code

The development of software and its maintenance was rather a hard way with a number of difficulties.

I strongly recommend those interested in history of software development to read article”No Silver Bullet – Essence and Accident in Software Engineering” by Fred Brooks in 1986.  Very interesting Wikipedia article states that: “Brooks distinguishes between two different types of complexity: accidental complexity and essential complexity. Accidental complexity relates to problems which engineers create and can fix; for example, the details of writing and optimizing assembly code or the delays caused by batch processing. Essential complexity is caused by the problem to be solved, and nothing can remove it; if users want a program to do 30 different things, then those 30 things are essential and the program must do those 30 different things. ”  Many scientists, software developers and businessmen noted that software grow faster in size and complexity than are invented methods to handle such complexities.  Some software companies initiated marketing slogan that their software is “intuitive and user friendly” which proved to be just marketing slogan far from truth.
All of that sometimes created great confusion . I felt like some botanist looking for magic flower in the middle of jungle.  I felt I was stuck in the middle of rainforest with gigantic trees, huge bushes, my skin crisscrossed with scratches and covered up with blood stains. It looked like I wanted to fit a square peg to a round hole. Enormous insects around me and snarling of hungry beasts was frightening. How did I get here?  How to get out from this?

In addition, increasingly complex software was often not well developed  and crashed frequently which caused even more confusion.  It was sometimes fun, but sometimes I have had embarrassing experience. A number of hours wasted, loss of data, broken hard disk.  I asked myself: What I have done wrong?  Is all of that really so sensitive that pressing wrong key on keyboard can toast my computer?  Who will use this stuff if it is so easy to ruin all I have done?

At the same time, business companies followed old devastating principles that everything should become commodity and they invested less in the development of supporting documentation.  They rather established support service that is not neither cheap nor efficient.  The free software movement gave to everyone free access to code being protected by GNU/GPL license which granted everyone right to develop, modify, distribute and document software as they like. That was promising framework and social, legal and technological basis for more responsible development and use of software.  At the same time users of many software packages experienced a lack of support, partly documented manuals, a variety of undocumented features, and sometimes unhelpful, arrogant and cynical support guys.

Even when manuals were written properly they were often very large and nicely illustrated books.  Too small number of people have had enough time to read them. I strongly believe that those who have had enough time for studying such manuals benefited a lot.

But, use of software manual is not based only on existence of sufficiently illustrated and written books.  Since I am more than 10 years involved in open access movement I strongly believe(d) that people from academia would use software manuals in a more systematic and principled way. But, my experience is very different.

There may be different reasons for that:

  • not sufficient time for reading detailed manuals
  • scientists and various scholars develop their own software for some purpose so they know it
  • software is developed for special purpose and it will not be used by wider audience
  • manuals and support are expensive or nonexistent
  • scholars and scientists are tired of reading and exhausting tedious work at academia so any additional obligation to read is rather avoided
  • some scholars and scientists display various psychological traits when being confronted with new scientific areas including software
  • some scholars and scientists have (un)diagnosed dyslexia, discalculia or other neurological conditions on a (sub)clinical level which prevents them from detailed reading of manuals, following procedures, remembering various relationships and hierarchies in managing various contexts managed by proper use of software features
  • some scholars and scientists for various reasons are print disabled and they do need assistive technologies to help them to learn to efficiently to use software

I am sure that there may be other reasons too.  But, those who write software and support scientists especially in the field of open access use of software should observe the following  principles:

  • written manuals should be written and tailored to the needs of some institution/library/journal
  • manuals should present procedures with examples from real use of software in a given context according to the version of software the is in production use by the users
  • manuals should describe each step in procedure or workflow and present screenshot that user see on the screen
  • manuals should be written in an accessible format
  • manuals should be enriched with infographics and other illustrations intended to present information in a brief and clear way.  They  can improve learning process by utilizing graphics to enhance the user’s ability to understand structures, workflows and procedures
  • manuals should offer links with screencasts that will show to the users how some tasks can be accomplished
  • software features that are invented with aim to improve workflow of users should be documented with examples of the real scenarios and contexts for a given group of users (i.e. journal, institute, faculty, library)
  • manuals, infographics and screencasts should be licensed with soem acceptable Creative Commons or GNU Free Documentation License

Well, one can say that it is not easy to do. But, software as manuals are a significant part of social interaction of various types of users (in the context of open access there may be readers, authors, reviewers, editors, librarians, lawyers, students, businessmen, policy makers). That is not commodity in a box. The manuals and software are part of ongoing incremental build model due to very dynamic development of various standards and services associated with academic publishing. Contemporary  software platforms require developers and users to take pace of the development of the internet, academic publishing, various technological, cultural, social, legal and scientific challenges and developments.  Consequently, when some editorial board or institution plans to deploy some software platform for academic and scientific publishing it is needed to plan continuous development, testing, support, documentation development and distribution.

Malware Intrusion

We know that there is no ideally secure server. I witnessed many times that hosting companies and their employees sometimes suffer from a lack of resources, equipment and skilled people that should take care on security of servers.  One of them tried to convince me that permission for folders in public_html should be 777. (If you are new to web applications and setting up your system for open access publishing please find on the internet information about permissions on your server. Majority of hosting companies with shared hosting accounts by default set that folders do have permissions set to 755 and files to 644.  Those people who want to compromise your server usually inject code that is planned to exploit vulnerabilities and use your server for some, usually illegal, operations as on image below.  When you in the process of choosing application, hosting company and person who will administer server the security should be top priority issue.

example of intrusion codeThere are various methods how to do that. Example on presented here was part of one larger file that was present on one server used to publish scientific journals.  Sometimes, servers are safe but applications installed are very vulnerable.  Strong competition and financial urges force developers to issue product as soon as they can without proper testing. I came across several times that some pieces of software are written for very obsolete and insecure versions of PHP which poses additional risks for security of site. On the other side, various additions of custom code that is not tested can make system insecure.

Such incidents can endanger your reputation and trust of authors, readers, reviewers and librarians that would like to visit your site often. Above all, sometimes some drivers, firmware, operating systems are vulnerable and you as user of one account cannot do anything to prevent that. That is job of people in hosting company and manufacturers of hardware with vulnerable software to fix vulnerable parts of software. Nevertheless, this should not discourage your from publishing open access.  Constructive and proactive caution is always necessary and welcome.


Once, I received call from one association that is publisher of one scientific journal. They informed me that some strange code appeared on their site and I used various malware testing tools and my result was like on image below. I found soon that server was infected so called db.php infection.  Since malware was successfully uploaded on server, it GET requests and it infects every javascript files (.js) with javascript malware code.encoded intrusion  I decoded strings displayed on page and I found IP address of server that is infected and which is used for distribution of malware and which redirects users to other sites. Since such code was all over the site it was very hard to read pages and visitors were prevented from using open access content.

I reported editorial board of the journal on my findings and we informed hosting company and domain registrar of domains used to spread malware asking them to check issue and undertake necessary measures to stop abuse of our and possibly other sites infected by that malware.

The process was rather tense, stressful and painful for editorial board and all people concerned.  The hosting company that hosted server with domain used for spreading malware informed us that they will take care on the case. 

We used other tools to block IPs that are detected as attackers. We have had that day more than 290 attacks from computers from Panama and more than 150 attacks from computers from Ukraine. We restored our site by using fresh backups and reinstallation of web applications we use.  Our hosting company upgraded PHP version that was obsolete, unsupported and insecure at  the time.