A Unified Format for Language Documents

We have analyzed a substantial number of language documentation artifacts, including language standards, language specifications, language reference manuals, as well as internal documents of standardization bodies. We have reverse-engineered their intended internal structure, and compared the results. The Language Document Format (LDF), was developed to specifically support the documentation domain. We have also integrated LDF into an engineering discipline for language documents including tool support, for example, for rendering language documents, extracting grammars and samples, and migrating existing documents into LDF. The definition of LDF, tool support for LDF, and LDF applications are freely available through SourceForge

Little languages : little maintenance?

So-called little, or domain-specific languages (DSLs), have the potential to make software maintenance simpler: domain-experts can directly use the DSL to make required routine modifications. At the negative side, however, more substantial changes may become more difficult: such changes may involve altering the domain-specific language. This will require compiler technology knowledge, which not every commercial enterprise has easily available. Based on experience taken from industrial practice, we discuss the role of DSLs in software maintenance, the dangers introduced by using them, and techniques for controlling the risks involved

Software maintenance: redocumentation of existing Cobol systems using hypertext technology

One of the major problems associated with the maintenance of existing software systems is their lack of documentation. This can make very large, poorly structured programs very difficult to maintain. Nearly all traditional documentation tools are either designed for use in the development stage of the software lifecycle or are report generators such as cross reference generators. The problems of lack of documentation are compounded when applied to third party software maintenance as the staffs are often initially unfamiliar with the code they are maintaining. This thesis describes these problems in detail and evaluates the feasibility of a tool to help with redocumentation based on current hypertext technology

Program automated documentation methods

The mission analysis and trajectory simulation program is summarized; it provides an understanding of the size and complexity of one simulation for which documentation is mandatory. Programs for automating documentation of subroutines, flow charts, and internal cross reference information are also included

THE USER INTERFACE IN INFORMATION PROCESSING: AN EMPIRICAL STUDY OF STUDENT PROGRAMMERS

The importance of human factors considerations is clearly recognized in the computing field today. However, there has been relatively little attention given to such issues in information systems and computer science curricula. This study examined the user interfaces designed by student COBOL programmers for an online, information processing application. A variety of problems were found in the visual displays and interaction designs suggesting a need for greater explicit consideration of this area in programming and software design training. A variety of suggestions are made as to ways of incorporating this issue into the curriculum

InfoTech Update, Volume 5, Number 1, Fall 1995

https://egrove.olemiss.edu/aicpa_news/4954/thumbnail.jp

The Readability and Usability of Building User Guides

Building user guides are intended to inform building occupants about the building systems within their workplace. They are created to describe and document all the necessary information pertaining to the buildings operation, maintenance, management and basic trouble shooting procedures. They have been found to be useful, as building systems are becoming increasingly complex. There is evidence to suggest that the Building User Guides are designed at a level that is too technical and too difficult to use for the average building user and that they are therefore not doing their job. This research evaluates how easily building occupants are able to read and use building user guides, that have been designed for use in green buildings (where they can contribute to the building’s New Zealand Green Building Council’s sustainability rating). Twenty-three Building User Guides by a range of firms and writers were sampled from all over the country. The building user guides were assessed for their readability and how easy they are to use. Their readability level was assessed using the Simple Measure of Gobbledegook (SMOG) as a basic measure of readability, while a second measure, a word frequency profiler was used to assess the vocabulary needed to read current building user guides. A usability study was completed through a user survey. This was completed by 47 respondents. The survey used both a Performance Test and a Text Evaluation Questionnaire to assess the building user guide’s usability. The readability study found that the building user guides were written at a level that meant the majority of New Zealanders would struggle to comprehend. The constant use of technical language and jargon present in the building user guides detracted from the overall readability of the document that. A consequence of these results would be the users failing to understand aspects of a building user guides. Furthermore, this could lead to the incorrect use of a building’s services, which in turn could affect the efficient use of GreenStar rated buildings and their performance in practice. The usability study found that users were capable of finding some set information within the building user guide. Of the tested aspects in the usability survey it was found that the contents page had the biggest impact on the participant’s perception of usability. Other key aspects found that would increase the usability include: bolder headings, a clearer layout, the addition of a frequently asked question section as well as the ability for the building user guide to be searched for key words. A set of guidelines were developed from the findings of this research, for future building user guides to follow