diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook index 982dbfb..c95d104 100644 --- a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook +++ b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook @@ -7,83 +7,81 @@ format is realized through the help functionality of centos-art.sh script, as described in . To illustrate the - production cycle, we'll describe it here, using the + production cycle, we'll describe it here using the Repository File System documentation manual as reference. - The first step before creating a documentation manual is to - make yourself an idea of what such manual intends to document. - The Repository File System emerged with the - need of understanding what each directory inside &TCAR; is - for, how they can be used and how they connect themselves one - another, as the repository structure itself is built on. - At the very begining, explaining something that is being - conceived is a rather difficult task, there are many small - concepts floting around that need to be organized in order for - them to take sense when it seen as a whole. So, I decided to - create documentation adapting the same principales I followed - to create functionalities inside - centos-art.sh script, as a way to - understand what I was doing. This way, if programs should do - one thing well, each directory inside the repository should be - documented well in order to better understand what they do and - how they relate one another. Later, summing all directory - documentations would let us, hypothetically, to correct the - whole idea in a repeatable cycle of improvement that would - consolidate the final idea we try to implement. + The first step for creating a documentation manual is to make + yourself an idea of what such manual intends to document. The + Repository File System emerged with the need of + understanding what each directory inside &TCAR; was for, how + they could be used and how they connected themselves one + another, as the repository structure itself was built on. At + the very begining, explaining the whole idea of all + directories inside &TCAR; on one manual was difficult, there + were many changing concepts floting around which needed to be + considered. So, as a way to understand what I was doing, I + decided to adapt documentation to such changes through the + same principales I followed to create functionalities inside + centos-art.sh script. This way, if programs + should do one thing well, each directory inside the repository + should be documented well in order to better understand what + they do and how they relate one another. Later, summing all + directory documentations would let me, hypothetically, to + correct the whole idea through an improvement cycle that would + consolidate the final idea I try to implement. Once you've make yourself an idea of what the documentation - manual is for, it is time to define the manual title and the - directory name where the manual will be sotred in. The manual - title describes, in few words, what the documentation manual - is about. The manual directory name must be a word or several - words separated by minus sign. As convenction, to set the - manual directory name, it would be useful to use acronyms or - abbreviations directly related to manual's title. In our - example, the documentation manual was initially titled - The CentOS Artwork Repository File System but - it was too long, so it was reduced to Repository File - System and the documentation directory name was set to + manual is for, it is time for you to define the manual title + and the manual directory name. The manual title describes, in + few words, what the documentation manual is about. The manual + directory name must be one or more words separated by minus + sign. As convenction, to the manual directory name, it would + be convenient to use acronyms or abbreviations related to + manual's title. In our example, the documentation manual was + initially titled The CentOS Artwork Repository + but later it changed to Repository File System + and its manual directory name ended up being Tcar-fs. - Once both title and directory name related to documentation - manual have been defined, it is time to create the - documentation manual and documenting your work through - chapters and sections inside it. At this point, it is - necessary some planification to set the way the manual will be - organized. The manual organization is set through chapters and - sections. In our example, the documentation manual is made of - three chapters named The The trunk Directory, The branches Directory and The tags Directory. Inside - each of these chapters there is one documentation section for - each directory in &TCAR;. + class="directory">tags Directory and one + appendix named License. Inside each chapter + there is one documentation section for each directory in + &TCAR;. To create a manual like that one described so far, you need to introduce such organization through the help functionality of centos-art.sh script, as - the following list of commands describes: + it is described in the following list of commands: - centos-art help --edit tcar-fs: + centos-art help --edit tcar-fs - ... + This command creates the tcar-fs manual base + structure and opens its main definition file with your + favorite text editor so you can fix values like title, + subtitle, author, etc. @@ -94,7 +92,9 @@ - ... + This command creates the introduction chapter + base structure and opens its main definition file with your + favorite text editor so you can fix the chapter introduction. @@ -105,21 +105,21 @@ - ... + This command creates the identity section + inside the trunk chapter. If the chapter + doesn't exist it will be created first. In this command, the + identity section refers to trunk/Identity directory inside + &TCAR;. To document other directories, follow the same + procedure but using minus signs to separate directories. For + example, to document the trunk/Identity/Themes you would + use tcar-fs:trunk:identity-themes, and so on + for other directories. - - - centos-art help --edit tcar-fs:trunk:identity-themes - - - - ... - - -