No day goes by without the release of new tools, services, programming languages, and software libraries, if not the latest version of any of these. It is easy to get overwhelmed, but what makes this rapidly changing technosphere further challenging is missing or proper documentation. Well-documented works make it easy for users and contributors to explore the solutions. However, non-documented solutions often fail to reach the targeted audience. It is indeed hard to properly document the different technological solutions. Furthermore, documentation of many small software solutions often gives the impression of software by the developers and for the developers.
What is the best way to document? How to attract the attention of new users or contributors? How to maintain up-to-date documentation? Often choices have to be made to reduce the number of options in software to simplify the usage and provide a minimalistic interface to the end-users. Such an approach reduces the need for maintaining the user interface documentation. Take, for example, the user interface of search engines. It is crucial to state that there are advanced options like the use of filters, especially aimed at power users. Nonetheless, in the case of simpler user interfaces, newer options are frowned upon by the users. Thus a compromise is required between a simple user interface and an interface with more advanced options.
As software or web services evolve, there is a tendency to add multiple options, rethink the user menus, etc. Often users end up complaining about minute changes in the user interface. What may look like a slight displacement of a button from the developer’s point of view, may affect the way the user’s brain had been programmed with the daily routine or habit, thereby creating a disruption. For the user, the new location of options has to be discovered.
This brings us to the importance of ‘how-to guides’ for software and technological solutions. Even though companies with resources provide ‘FAQ’ (frequently asked questions) to respond to the different questions related to working with their products. These answers are often limited to very few human languages, like English. Moreover, if a product has a more global reach, the translation requires help from multiple translators. As discussed above, the task becomes difficult when software evolves very rapidly, often leading to outdated documentation in many translated documents.
There have been several attempts to generate automated documentation. Static pages or dynamically generated pages are automatically generated for the application programming interface (API) or the software development kit (SDK) of service and software products. Static pages are well indexed by most search engines, while the indexation of dynamically generated pages is limited to some popular search engines. For a large product, API, or SDK, dynamically generated pages can handle a multitude of options. Nevertheless, it is better to periodically generate static pages from them.
Automated documentation does not yet cover the end-user interface (or front-end). It is long overdue that developers consider the significance of linking the user end options to their code to ensure that ‘how-to guides’ or FAQs reflect any minute modifications. The users may not need to struggle to find a particular feature after the release of a newer version.