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.