IEEESatndard10632-001of,rdocumenatoitn

uoesfrs
Having a standard for user documentation
software is necessary. The Std 1063-2001 provides a good guide for
create an appropriate user manual

Many of us find ourselves in the area of systems documentation.

it was less my case) by coincidence. The first time one has an approach
with the area has an understanding of the documents that must be part of a development or
software product, but nevertheless is unaware of which parts or sections it should
contain those documents. For example, what sections should a manual have?
user?, or a technical memory?, etc.

The IEEE Std 1063-2001 standard provides that framework to establish what
parts must make up any document that is to be used by a user of
system or program in question.

This standard only applies to user documentation, for the documentation of

technical character other recommendations are used which we will discuss in your
moment. Broadly speaking, the IEEE recommendation establishes the following parts
for a document that users will use. These parts are:

1.- Identification of the data (package, title)

2.- Table of contents, in documents with more than 8 pages
3.- List of illustrations (optional)
4.- Introduction
5.- Information for the use of the documentation
6.- Concepts of operations
7.- Procedures
8.- Information about software commands
9.- Error messages and troubleshooting
10.- Glossary
11.- Referencias
12.- Navigation Features
13.- Index
14.- Search tools (in electronic documents)
What is documentation?
Let's think of names like Leonardo Da Vinci, Isaac
Newton, Galileo or someone else. We all know what they have done.
But could we remember them if we didn't have
registration of your ideas or inventions?.
In the case of great thinkers, women and men, of humanity their legacy to
It has been captured in books, this is his work and thought has been documented.

The documentation is based on the scientific method. With the intention of

to be able to replicate the experiment or experiments conducted to validate some thesis, the scientist
record all the conditions under which the experiment is conducted, equally
In this way, the results are written in tables and these in turn generate graphs.
statistics that allow us to interpret them. Currently, the means to carry out the
The records of some activities are very diverse, with digital ones being the most used in
the present.

Now we will define documentation as the process of recording in a manner

organized the procedures and results obtained throughout a research
scientific or project or in general any activity that needs to be repeated more than
for example: a well-documented cooking recipe should include the time
cooking exactness and the exact temperature at which the dish reaches its best
properties.

Documenting allows us to make the leap between the empirical and the scientific, between chance and
las mejores prácticas.

Documenting an information system involves storing and organizing the information.

necessary (in the form of written or graphic document) with the intention that upon
to finish the project we can: maintain it, improve it, and/or repeat it. The amount of
documents generated throughout the project will depend on the team that builds
the software and the development frameworks used by the organization. In addition, in the
In the case of business projects, documentation must be kept even for the
hardware configuration where the constructed systems are deployed.
From the above, I would dare to give the following Classification of the Documentation:

Administrative documentation:

It refers to the documents that are part of the context of the administration of
project as such: Work plans, Project definition, Definition of roles and
profiles of the project members. Cost analysis, Risk analysis, etc. In
this place, for example, we could put all the documents of the management of
projects established by the PMBOK.

2. Technical documentation:

a) Software development.

In this section, you can place the documents related to the cycle of
system development. Similarly, the number of documents varies according to the
framework used to create the software product. In the case of a
classical approach where the life cycle of systems is defined as: Analysis,
Development, Testing, and Implementation, we would have documents such as: Catalog of
requerimientos, digramas UML, Solución propuesta, Diccionario de Datos, Diccionario
of forms, Catalog of objects, Commented source code, Test plan,
["tests and results","Implementation or deployment plan","Installation report"]
User manual, Administration manual.

A more agile framework like SCRUM would not require so many documents in its place.
I would consider it more than sufficient for the code to be commented according to the standard of the
language, for example in Java the JavaDoc format should be used.

b) Applications used.

In the case of enterprise applications where, in addition to developing software,

some programs that are already marketed are used, we must keep the
installation report of the various applications that make up the platform.

c) Hardware components

A record of the hardware configuration on which it is to be stored must be kept.

installing the application, we must remember that what we want is to replicate the process
more times, so the omission of the configuration that the hardware has can be
crucial to achieve the expected results.
3. Processes.

Having processes documented based on standards will allow companies to evaluate them and
improve them. The client's processes help us to adapt the software product to
the company. The company that develops the software or offers IT services can
find great support in frameworks like ITIL.
Let's close the topic considering the following:

The documentation allows repeating the software development cycle.

It allows for continuous improvement
3 Establish the foundations of business knowledge
4 Marks the standard of software quality
5 Allows to measure the progress of the project
6 Establish a legacy for the next generation of developers
I finally believe that any medium to large-scale software project,
what is not well documented is doomed to failure and oblivion. On the other hand, not
there is a standard list of documents, in any case the list of documents depends
of the methodologies and frameworks used in its development and of the
indications from the management staff, that is, what do I want to be documented, from a
specific product?

How
w
otu
am
estrianu?al
To know in detail the process or system for which it is required
manual, it is the backbone of all good documentation of
user
Recommendations for writing a user manual

The process of creating a user manual is simple as long as you

Please keep in mind some points that should be followed in sequence to avoid
losing ourselves. The first step to writing the manual would be: Identify the user of the
Documentation: Who will be the potential readers of the document? This helps us
will help to determine what technical level should be used in the document and of
some way to frame your content.

The second step will be to define your table of contents. We need to know that
information will be placed in it and in what order. A good practice is to place the table
de contenidos en una matriz, en una hoja de cálculo, para ir señalando el avance de
each topic or process and in that way understand the progress of what we are writing and
your relationship.

Third, organize the content. A recurring question is what should be included in

a user manual or how it should be organized?. Well, I use two approaches:
Include the use cases in the index and classify them according to the users who use them.
they use or organize the information by functionality.

For example, let's suppose that a point of sale program was designed and some of
its use cases are:

7 Register a product
8 Modify the product price
9 Start sale
10 Complete sale
11 Review stocks
Well, a list of use cases can be placed and started to describe them or
we can organize the index according to the functionalities or the processes that
they can do in the system, for example:

1 Make a sale (this process definitely needs to include the use cases Start sale)
and complete the sale)
2 Review inventory (in this process it may be necessary to upload new products or
modify the price of some and check the inventory in the warehouse.
Fourth: Gather and classify the information for each topic or subtopic within the
document. Although this point is placed in fourth place, it is essential that
Let us have a data warehouse before the preparation of the document.
Having a repository of information gives us the possibility of having a warehouse
centralized information, so that searching and classifying it is easier. (you can see
how to install SVN in your organization in the followinglink.
Una vez que hemos cumplido con los cuatro puntos anteriores debemoselegir una
structure or formal framework for our manual. Personally
I use the IEEE std-1063-2001 standard as a reference. It specifies the parts.
What any user documentation should contain.

Now we should start writing the manual, although first we need to decide on
What format and with what software will it be created, my recommendation is DocBook (you can
see more information about its use in the followingDocBook tutorialIt should be considered
that a manual is designed for different user profiles, so sometimes
It is advisable to create different versions so that the actor in turn can perform all of them.
the functions allowed by their profile. Therefore, it must be clear and descriptive, that is,
leave nothing to the imagination, nor to the user’s assumptions, make the notes clear or
prerequisites that the user will require to execute the procedure smoothly,
It must contain clear and detailed images, which should be placed in an index.
and have a description of the image. Once the manual has been completed.
it must be evaluated and reviewed by the programmers or testing engineers with
the intention to validate that your instructions are appropriate and lead to a result
successful if followed to the letter.

It is certain that writing a manual or any technical document requires the person who
writing skills, strengths, and solid knowledge of grammar, composition and
spelling with the purpose of being well done. It should also be remembered that a
good documentation, in this case a good manual, can make the difference between the
success or failure of the system in its implementation.
Mn
im
i umdocumentatoinofasoftwareproject
The documentation of a project is an essential part of the
activities that must be carried out for proper development,
implementation and maintenance of it.
What documentation should the system have?

One of the first things a documenter must do is understand the area,

tasks that will be under your responsibility and the specifics of the project.

The following definition from Wikipedia gives us a glimpse of what the Documenter is.
of systems will face:
In a restricted sense, documentation as documentary science could be defined
(broadly speaking) as the science of information processing, that
provides information about something with a specific purpose, in a multidisciplinary context
or interdisciplinary.
Following Fuentes and Pujol, Documentation can be identified as a science.
auxiliary and instrumental. It is also a science in itself and one of its purposes
The primary purpose of documentation is to inform..1In the absence of a consensus, there are various
authors, such asJuan Ros García oJosé López Yepes, which they consider a science
(documentary), at the same time as a discipline, not just a technique. They can also
considered, in general terms, the sciences of documentation and documentation
as synonyms, if the context does not disturb the intention of the sender, that is, if it does not
it distorts the message of the interlocutor because it does not give semantic ambiguity.
For ITIL V3, the knowledge possessed by collaborators (own knowledge or
owner) and that have been gaining over time, it is useless if it does not adapt to
standards and is socialized. It will always be advisable to document the processes,
adhere to industry standards and prevent business knowledge from
only a few people accumulate.

The IT project documentation must be adapted to the established needs and to

the methodology or framework on which it is being developed. However
there are fundamental documents according to the stage or life cycle of the system in
that is found.

The PMBOOK, for example, establishes the administrative and control documentation that
must be associated with the project. ITIL gives us an idea of the documentation that should exist
to provide services appropriately. Other specific standards for
the coding such as: JavaDoc or user documentation proposed by the IEEE,
They must be established by the documenter and followed by the programmers.

Software development methodologies provide a guide for the documentation that

It is necessary to have, although generally, it will always be required to create: the catalog.
requirements, data dictionary, UML diagrams, the work plan, the plan of
implementation or deployment, the training plan and change control.

Depending on the language in which the project is being developed, it must be

establish the documentation pattern for example: JavaDoc, JSDoc, JSON, PHP, etc.

The following diagram shows the different stages and areas of an IT project and the
documents associated with each of them:
Finally all the files including user documentation, administrative,
budgetary and procedures, must be placed in a repository under which there is
a version control system. Personally, I recommend the use of SVN Subversion or
Git, although there are many more.

Once the environment for storage and control has been established
documentation and after determining which documents are to be
to be carried out throughout the project, the format in which they will be determined must be established
captured and distributed. These formats can be: Word formats or some other
word processor, LaTeX, DocBook, etc.