Software Development Life Cycle & Documentation

Introducción

• Software development involves processes from conception to obsolescence.
• These processes are known as the software development life cycle.
• Documentation is generated for each aspect of the life cycle to gather relevant information, such as installation manuals or user guides.
• Careful version control is essential to prevent issues like data loss or using outdated versions.

Documentación del software

• Documenting all software project processes with an established structure and standards is essential.
• Accessible, high-quality documentation prevents problems such as client misunderstandings, difficulties in project modification, and challenges during team replacement.
• Good user manuals enhance user autonomy and satisfaction.
• Reasons for lack of documentation:
  • Tight deadlines
  • Lack of company culture valuing documentation
  • Developers finding documentation tedious

Documentation Best Practices

• Documentation should be understandable and tailored to the audience.
• Structure the document well, including an index.
• Enforce standards with defined templates.
• Start with a clear introduction outlining document contents.
• Include contextualized examples in technical documentation.
• Incorporate schemas, screenshots, and a standard file format.
• Clearly state the documentation's edit date and program version.
• Focus on essential information and regularly review document validity.
• Make documentation easily accessible and allow for user participation.

Control de versiones (Version Control)

• Programs have many modifications throughout their life cycle, including error corrections, improvements, and adaptations to market needs.
• Managing these modifications can be complex, especially in larger projects.
• Version control is essential for orderly development of code.
• It helps to know what version is being worked on and who made the changes.
• Optimized version control goes beyond backups and offers advantages such as:
  • Quickly reverting to previous project states.
  • Improving team focus and development efficiency.
  • Providing traceability of changes for understanding code functionality.

"Man" Command in Linux

• The "man" command provides a user interface to access reference manuals in systems like BSD, Unix, Mac OS, or GNU/Linux.
• Reference manuals are classified into numbered sections, typically from 1 to 8, including:
  • Executable programs and shell commands.
  • System calls (kernel functions).
  • Library calls (library functions).
  • Special files (e.g., configuration files).
  • File formats and conventions.
  • Games.
  • Miscellaneous items (macros and conventions).
  • System administration commands.
• The basic syntax is: man [man options] [[section] page].

Table Definitions

• $ man passwd shows help for the passwd command in section 1.
• $ man 5 passwd displays the format of the /etc/passwd file in section 5.
• $ man -a passwd shows all the help pages for passwd in any sections that coincide.
• $ man -f passwd prints the short descriptions of passwd found in all the sections.
• $ man -k passwd prints short descriptions of entries that coincides with “passwd.”

MediaWiki

• It is a web application offers a collaborative wiki platform for software documentation.
• It provides a free, open-source platform for multilanguage content.
• Permissions can be set for who can change the content.
• Older versions are saved in case that the current one needs to be recovered.
• Information is stored in pages and grouped in the spaces of names.
• The pages are written in wikitext which is HTML based.

Wikitext formatting explained:

• == Title 1 ==: first level heading.
• === Title 2 ===: second level heading.
• "Text": italics, '''Text''': bold, """Text''''' : bold and italics.
• [[Page]]: internal page link, [[Page Title]]: link with alternative title.
• [URL Title]: external link with alternative title.
• • Text: unnumbered list element, :Text: paragraph with first level indent.

Javadoc

• Javadoc is an Oracle tool for generating technical documentation in HTML from Java code.
• It uses comments in the files for reference to generate the documentation automatically.
• The comments should be before the declaration of a class, field, constructor, or method.
• These comments must follow a structured format:
  • Begin with a line containing the delimiter /**.
  • End with a line containing the delimiter */.
  • Each line in the comment starts with *.
  • The description (can include a short first line and longer detailed segment).
  • A section defining sets of tags preceded by @symbol and description.

Javadoc Comment Considerations

• Each comment line should be a maximum of 80 characters.
• @author indicates the author of the classes and interfaces, and it is obligatory
• @version displays the version of the classes and interfaces, and it is obligatory
• @param displays and describes the name of the parameter
• @return describes what the method will return
• @exception and @throws indicate what type of exception is expected

Version Control Concepts

• Repository: Storage space for source code and metadata, intended as the definitive version.
• Change: A modification made to repository files.
• Conflict: Occurs when multiple modifications happen to the same file, needs resolution.
• Revision: A version of a file identified by a number.
• Branches: Parallel development paths.

Known Version Control Tools

• Apache Subversion (SVN): Uses a client-server repository model.
• CVS: Client-server model, allows multiple programmers to work simultaneously, handling conflicts manually.
• Git: A distributed system working with HTTP, FTP, and SSH protocols.

GIT

• Under GNU 2.0 license.
• Available for GNU/Linux, macOS and Windows.
• Written in C.
• Faster than other options.
• Flexible branching model.
• Has dedicated branches for different tasks.
• Merging/eliminating between branches.
• Initial configuration applies to all the users.

GIT areas of work

• Working directory: a copy of the repository files available for modification
• Staging area (index): an area that storage changes.
• Git directory: an area that contains project and metadata with an older version of it

File status

• Unmodified: a copy of the working area and has no change so far.
• Modified: change copy after it was obtained. Was not still added.
• Staged (Prepared): an area that prepares and confirms an area if the copy makes changes already. Committed: a file confirms and registers in the repository.

Git Commands

• init: creates the repository
• clone: clone it from the new directory
• add: attach contents from one file to one area
• status: shows areas state from the user.
• diff: shows the difference among confirmations
• commit: creates new version content from the current area version.

GIT continued

• notes: add notes without altering them
• restore: restores files with no source work
• reset: the user reset HEAD to the selected state.
• rm: removes files from work directory, or from the user.
• mv: moves or renames director and files
• branch: Lists, creates, or deletes branches.
• Checkout: Change the branch or restores.
• mergetool: tools used to solve branch issues and conflicts.
• log: Shows registers of the confirm.

GIT end

• stash: tests changes, so that the user can come back.
• fetch: upload objects
• Pull: uploads it.
• Press: press new version of the tool.

GitHub

• There is a user creation and type, as well as the groups.
• GitHub is more than a basic code.
• The site provides options as code.
• Every student, or company, can find their place in the area.

GitHub accounts for higher education students

• Can be more that space for the user to manage the place.
• Educational toll that allows learning control, versions and collaboration
• Can share projects or make assignments as groups.

Professional developer accounts

• Can find a collaborate open space where users can contribute
• Share their experience with community
• Can manage with team
• Track issues with the pull features

Company/organization-based accounts

• Have better solutions.
• Used for tools, actions, project management
• Improve collaboration team

Open Source project maintenance accounts

• Maintain open better sources for the team to use.
• Maintained by 10s, 100s, or 1000s users.

Enthusiast and Amateur Users

• GitHub attracts users that are interesting in common tech/programs.
• In resume: GitHub has more that users can used them.
• Can work with CI continuous, whose point focuses in time and application.
  • CI: programming changes tested automatically.

CD: to publish new version of tools

• Verify correct modification the the developers make
• Hosted by GITHUB to automate.

GitHub type account

• It has convert to tools.
• Collab, versioning, efficiently project edition with managed way.
• The GitHub type account has: an account that can give limited functionalities compared by the payed account.
• It's a way to let the partners in college/class works code together
• The follow problems can be solved between: problems, code extras, task and fixes.

PRO accounts

• More control and advanced features that are popular.

Team for accounts

• designed to provide advanced access, review code, and improve tool security.