Opensource.Platon.SK CVS: doc/soft-doc-sys/sgml/en/introduction.sgml - diff

   Up to  [Platon] / doc / soft-doc-sys / sgml / en
Diff for doc/soft-doc-sys/sgml/en/introduction.sgml between version 1.2 and 1.3


version 1.2, 2002/12/11 18:16:12
version 1.3, 2002/12/16 11:48:38



Line 1 




Line 1 




 <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->
 <!-- $Platon: Platon.SK/doc-projects/soft-doc-sys/en/introduction.sgml,v 1.2 2002/12/11 18:16:12 nepto Exp $ -->


 
 


 <chapter id="introduction"><title>Introduction</title>
 <chapter id="introduction"><title>Introduction</title>


 
 


 <para>
 <para>


 
 


 
 Almost every software developer has sometime in his life been confronted with


 
 the problem of documenting his project. This, one would say banal matter,


 
 consists of more problems than one would think. Software that does not include


 
 quality detailed documentation is heading for downfall.  In our document we will


 
 try to illustrate some of the possibilities for quick and effective


 
 documentation of software product.


 
 


 
 </para>


 
 <para>


 
 


 
 The basic factor to think about is the target group.  Common software user is


 
 interested in different type of information than <!-- potencial --> application


 
 developer.  This needs to be taken into consideration. One needs to adapt the


 
 form and content of documentation.  That is why distinguish two different types


 
 of documentation:


 
 


 
 </para>


 
 <para>


 
 


 
 <orderedlist numeration="arabic">


 
 <listitem><para>User-oriented documentation</para><para>


 
 


 
 Common user is usually not interested in software architecture nor it.s inner


 
 implementation.  He or she does not care how things are done, what means and


 
 programming languages were used in the process of development.  What interests


 
 him/her the most is how the program runs, how is it used and also in what


 
 environment and under which operation system it can be started.  That is why the


 
 emphasis should be put on detailed, but mainly understandable explanation of all


 
 functions and possibilities of the program.


 
 


 
 </para>


 
 <para>


 
 


 
 It is better if someone else than the author of the program writes the


 
 user-oriented documentation.  He may consider many things to be absolutely clear


 
 while they may not be clear at all to the common user.  It is appropriate if the


 
 user-oriented documentation includes many examples and is written in awareness


 
 that it will be read by person who doesn.t understand programming at all.


 
 


 
 </para></listitem>


 
 <listitem><para>Developer-oriented documentation</para><para>


 
 


 
 A developer working on a project needs to have documented all the inner


 
 technical matters of the software, such as class inheritance hierarchy, data


 
 structure description as well as it.s attributes, list of source files, global


 
 identifiers etc.  The description of the correct use of corresponding


 
 development tools used for the program creation should also be included.


 
 


 
 </para>


 
 <para>


 
 


 
 The basic purpose of existence of developer-oriented documentation is the


 
 maintenance and extensibility of the software product.  It is an absolute must


 
 to document all the nonstandard program constructions as well as a detailed


 
 description of the process of synchronizing the program.


 
 


 
 </para></listitem>


 
 </orderedlist>


 
 


 
 It is now clear that these two types of documentation are absolutely different.


 
 It is not possible that the documentation of the first type replaces the second


 
 or the other way around.  The developer-oriented documentation should be written


 
 along with the program creation.  If the inner implementation of structure


 
 changes, the corresponding part of documentation is changed as well.  It is


 
 reasonable to start writing the user-oriented documentation as soon as possible,


 
 but this should not be before the program reaches it.s basic functionality.


 
 


 
 </para>


 
 <para>


 
 


 
 Both types of documentation are written by different people and the tools for


 
 its creation and maintenance are adapted correspondingly.  Their use is


 
 illustrated in the following chapters of this document.


 
 


 </para>
 </para>


 
 









Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3


















Platon Group <platon@platon.org> http://platon.org/
  Up to  [Platon] / doc / soft-doc-sys / sgml / en
-version 1.2, 2002/12/11 18:16:12
+version 1.3, 2002/12/16 11:48:38
 Line 1
 Line 1
 Line 1
- <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->
+ <!-- $Platon: Platon.SK/doc-projects/soft-doc-sys/en/introduction.sgml,v 1.2 2002/12/11 18:16:12 nepto Exp $ -->
  <chapter id="introduction"><title>Introduction</title>
  <para>
+ Almost every software developer has sometime in his life been confronted with
+ the problem of documenting his project. This, one would say banal matter,
+ consists of more problems than one would think. Software that does not include
+ quality detailed documentation is heading for downfall.  In our document we will
+ try to illustrate some of the possibilities for quick and effective
+ documentation of software product.
+ </para>
+ <para>
+ The basic factor to think about is the target group.  Common software user is
+ interested in different type of information than <!-- potencial --> application
+ developer.  This needs to be taken into consideration. One needs to adapt the
+ form and content of documentation.  That is why distinguish two different types
+ of documentation:
+ </para>
+ <para>
+ <orderedlist numeration="arabic">
+ <listitem><para>User-oriented documentation</para><para>
+ Common user is usually not interested in software architecture nor it.s inner
+ implementation.  He or she does not care how things are done, what means and
+ programming languages were used in the process of development.  What interests
+ him/her the most is how the program runs, how is it used and also in what
+ environment and under which operation system it can be started.  That is why the
+ emphasis should be put on detailed, but mainly understandable explanation of all
+ functions and possibilities of the program.
+ </para>
+ <para>
+ It is better if someone else than the author of the program writes the
+ user-oriented documentation.  He may consider many things to be absolutely clear
+ while they may not be clear at all to the common user.  It is appropriate if the
+ user-oriented documentation includes many examples and is written in awareness
+ that it will be read by person who doesn.t understand programming at all.
+ </para></listitem>
+ <listitem><para>Developer-oriented documentation</para><para>
+ A developer working on a project needs to have documented all the inner
+ technical matters of the software, such as class inheritance hierarchy, data
+ structure description as well as it.s attributes, list of source files, global
+ identifiers etc.  The description of the correct use of corresponding
+ development tools used for the program creation should also be included.
+ </para>
+ <para>
+ The basic purpose of existence of developer-oriented documentation is the
+ maintenance and extensibility of the software product.  It is an absolute must
+ to document all the nonstandard program constructions as well as a detailed
+ description of the process of synchronizing the program.
+ </para></listitem>
+ </orderedlist>
+ It is now clear that these two types of documentation are absolutely different.
+ It is not possible that the documentation of the first type replaces the second
+ or the other way around.  The developer-oriented documentation should be written
+ along with the program creation.  If the inner implementation of structure
+ changes, the corresponding part of documentation is changed as well.  It is
+ reasonable to start writing the user-oriented documentation as soon as possible,
+ but this should not be before the program reaches it.s basic functionality.
+ </para>
+ <para>
+ Both types of documentation are written by different people and the tools for
+ its creation and maintenance are adapted correspondingly.  Their use is
+ illustrated in the following chapters of this document.
  </para>
 Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3
 Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3
-Removed from v.1.2
+Added in v.1.3


Copyright © 2002-2006 Platon Group Site powered by Metafox CMS	Go to Top