From igc.apc.org!notes Sun Nov 29 15:37:52 1992 From: arni@web.apc.org (Arni Mikelsons) Date: 24 Nov 92 13:18 PST Subject: - Documentation and Translation To: Recipients of conference "tech.smallsys" Message-Id: <269400020%web.apc.org@igc.apc.org> Translations and Documentation Documentation of ELF (Easy Link to Fido) was identified at the Global Networking Workshop as crucial in the development of electronic communications in Africa. The need for information and instructions in a user friendly format is vital to contributing towards local sustainability of host and user systems. It should: - enable host system operators to confidently offer local on and off line assistance; - enable users to refer to documentation which will answer the most frequently asked questions; - be informative and instructional enough to interest new users with little or no knowledge of electronic mail. The documentation should take the reader through an introduction to electronic mail and networking, offering assistance with installation and descriptions of the various programmes used in the software and, most importantly present clear and precise operational guidance for a new user or host operator. User Documentation History and current status of user documentation Initially the documentation distributed to new users consisted of various text files written by Mike Jensen which were included in the floppy disk distribution of the Front Door Menuing (FDM) system. The documentation accompanying FDM included: - outline.txt - an overview of electronic mail networking, descriptions of GreenNet, GnFido and the Association For Progressive Communications; - fdm.doc - a simplified version of the official Front Door Manual; - frodo.doc - the official Front Door Manual As the FIDO/APC network developed, additional documentation was written and incorporated into the floppy disk distribution. This included: - poll.txt - a FIDO/APC connectivity map - trouble.txt - the most commonly experienced modem, phone and conference maintenance problems - oxfam.q&a - some additional 40 or so 'commonly' asked questions from Oxfam, UK. - nodelist.txt - instructions for reading nodelists - fdguide.txt - see below Fdguide.txt description Fdguide.txt is a comprehensive guide to Front Door written in French and English. It includes sections on electronic mail, other programmes within the floppy distribution such as an alternative editor, conference manager etc. and reference guides to function keys. The following is an overview of the major areas covered by the document: - Introduction: Overview of Electronic Communications - what is a computer network, e-mail, gateways - Fido addressing - system overview - how different components work together (through batchfiles) - explanations of each part (editor, mailer, tosser/scanner, etc) - using the menu system - description of editors (GoldEd and Front Door) - reading messages - conference areas - addressing - making a new message - changing a message - description of the Mailer (Front Door) - quick reference charts for the editor (GoldEd and FrontDoor) All of the files mentioned above are included on disk with all distributions. It should be noted that this documentation was incorporated in addition to any official electronic (on disk) manuals which accompanied the software components of the distribution. The documentation cited above was developed in response to the growth of the network and the need for less technical versions of the official programme documentation. Most of the work on documentation to date has been done by system operators and trainers already over-extended by technical, training and 'in the field' commitments. It has served, along with on-line support, new users in several African countries (and to a lesser extent users in Europe and Asia) to the point that there now exists a backbone of operating nodes with associated users in Africa which will be able to support a long term, locally sustainable network. What is now needed is documentation that is edited and produced by professional, non-technical staff designed to support the ongoing growth of the network. Proposed user documentation The Global Networking Workshop participants decided that the new documentation should be based on the existing documentation, but should incorporate several major conceptual changes and modifications including: - a professional DTP level of production; - translations into French; - an orientation towards a more "hand-held" approach using visual aids eg. screen captures co-ordinated with any electronic on-line help available in the programme, graphic depictions of the route electronic mail takes from the PC to modem and along various gateways to its destination, etc. A new manual, based on elements of Fdguide.txt, should include the following sections: Introduction: Overview of Electronic Communications - what is an electronic network and how can it help the user network more effectively with special reference to the African context; - description of the APC and associated networks (from outline.txt); - description of the other services available to email users eg. fax and telex; - map of FIDO/APC connections/gateways (from poll.txt); - description of other electronic networks eg APC, Internet, Bitnet etc - different addressing formats eg. APC/Fido/Internet/Bitnet System Overview - how different components work together and why they are used (including diagrams and graphics) - complete accompanying documentation for each component of the programme (editor, mailer, tosser/scanner, etc) - batch file and menu system use Installation of ELF for a new user - step-by-step guide to software installation your own software and configuration the system to suit your own needs Addressing/Users - how to read 'address lists' (Nodelist/point list), including non-fido address lists Description of Editor - reading messages - replying to a message - creating a new message - altering a message: address, subject, status, content - importing text files into a message - creating file attach messages - creating compressed file attach messages Conferences and conferencing - what is a conference - subscribing and unsubscribing to conferences - maintaining folders and areas to organise conference material - writing messages to a conference Description of the Mailer - how to request files while in the mailer - how to read the mail history Appendices - quick check-list for beginners - glossary of all terms used in the manual and terms which may come up in electronic mail discussions - quick reference card to the function keys used in the editor and mailer - modem and phone trouble-shooting guide (including trouble.txt and oxfam.q&a) Complete Index Host Documentation History and Current Status of Host Documentation Currently, host operators are using the existing documentation distributed to users. However, the complexities of operating a host are far in excess of those of users, and additional support has been offered in various other forms: - official documentation accompanying the various maintenance components of the current programme suite, eg. Imail, Tosscan, redirection utilities, message tracker utilities, areafix managers, etc. - on-line support from other system operators - periodical on-site training workshops Development of Host Documentation The host software documentation will reflect the complexity of operating a node supporting between 5 and 100 users. In addition to the user documentation, particular attention will be given to the various maintenance procedures necessary for host node operation: - detailed explanation of electronic networking - detailed description of the different gateways and systems, eg. how to connect to a university site with particular focus on the different address formats - information about the importance of participating in electronic system operator support and policy conferences - extensive troubleshooting guide for user (point) installations including information covering: - typical hardware problems experienced, eg. serial port driver, monitoring disk space - amending autoexec.bat and config.sys files where necessary - connecting modems to the telephone exchange - making calls with operator assistance - using existing host PC utilities, eg. mouse, Desqview with ELF - a separate and extensive guide to modem operation from trouble shooting through to successful configuration - description of the GOFDHOST batch file which drives the host system, and details of the error levels that are returned during its execution - separate documentation sections on all of the different programmes used in ELF - fossil driver - mailer - editor - message splitter - message tracker - redirect utility - sent message mover and renumbered - conference manager - nodelist compiler and updater - archiving tool - detailed explanation of the Fido routing commands - description of the cc function in the editor and other advanced features - more detailed explanation of conferences (sometimes called folders or boards) set-up, scanning for unread mail, moving messages between folders, etc. - additional conference maintenance support, eg. conference traffic monitoring, utilities for maintaining the conference message base, eg. purging material, packing and sorting message base, setting up public and private conferences - analysis of mailer and conference management logs including monitoring of data transfer rates, costing of different polls, etc. - maintenance, trimming, updating and distribution of point and nodelists - operation of accounting software and production of bills for users As proposed under Host Software, there would be two "host upgrades". The first would run on basically the same programmes as the user software, remain free of charge, but would include host- specific programmes such as tracking and billing programmes. The second, the "advanced upgrade" would include programmes that are quicker, to minimise downtime, and which hold up better under heavy usage. In addition to the host documentation that must be created, most of the programmes used include documentation. This is often very technical in nature, but for a host operator, these documents are necessary. Also included with every installation is a document called Policy 4, which is the Fido policy document. Development Time Frame The documentation, for both ELF and the host upgrades, will be developed in conjunction with the time-line for the software development plan. The documentation will be developed in two stages: Medium term (3- 6 months) Using the structure of the current documentation, documents will be written to accompany the release of the test versions of ELF to system operators in the field who will help evaluate both the user and host software. Long term (6 - 12 months) Full documentation will be included with the test release of ELF (User software). The documentation process will also provide a period of thorough debugging and testing as the documenters work their way through all functions of the software. The release of ELF 1.00 will include thoroughly tested software with completed documentation, and will be within 12 months of the beginning of the project. Translation The completed documentation will be translated into French. The translated documents should be ready with the official release of ELF 1.00. The desktop publishing and production of English and French documentation will take approximately 6 weeks.