On Software Development (or "O Sr. SiIva disse..."): maio 2016

quarta-feira, 25 de maio de 2016

FUN Dept.: About Early Deliveries (and the relation to Incompetence) | Dilbert

Have you been on a project that delivered in advance? Did you ever finish a task earlier than planned? Good! Don't ever think on following this advice:

FUN Dept.: Predictable persons | Dilbert

INSTALL: Sparx EA

To install and configure EA to use the floating license, starting from https://delivery.critical.pt/TechAreas/net/SitePages/ToolsPage.aspx select Enterprise Architect (https://delivery.critical.pt/TechAreas/net/SitePages/ToolEnterpriseArchitect.aspx). Look at the PDF with the installation instructions (INTERNAL).

You can also download a free trial from the Sparx Systems WWW site.

Configuration Management: Version Control System (VCS) and standardized folder structs

To support the CM activities, your company will make available a tool that can be called generically Version Control System (VCS).

Examples of such systems are Git, CVS and SVN (Wikipedia article here and comparison here).

Your QMS could have a Version Control System GBK (INTERNAL) to speed you up.

This guidebook also could be indicating common standard repository structures (per project type) so that when you move from project to project you'll know right away that you'll find meeting minutes in the same (relative) path, e.g. "quality-management\meeting-minutes", code under the "implementation" folder, requirements documentation under the "requirements" folder, and so on.

Folder structures could be different per project type, i.e. software development projects could have a different template used for initial folder strucutre creation than other of another project type (e.g. Services, R&D, etc.)

PS. BTW, are you a git (in VCS terms)? If so, do not complain to me, complain to Linus, Maybe because "He's such a stupid get" - John Lennon (quote from the "I'm so tired" Beatles song).

quarta-feira, 18 de maio de 2016

Fun Dept.: How's Work? | Dilbert

If you are doing software engineering with a "bad" team and/or leadership or without a proper [software develoment] process here's how you could be feeling:

segunda-feira, 16 de maio de 2016

RESOURCE: TIOBE Index or "the manhood index for programmers" (if they are men)

The Short Story

The latest version of this monthly rank can be found here (COBOL still appears on the second part of the ranking, and VB is pretty much up in the ranking): http://www.tiobe.com/tiobe_index?page=index

The rationale behind the calculations (or the index definition) is described here ("unfortunately" porn sites are excluded - just kidding).

The Long Story

Let me quickly share the TIOBE Index, aka as "the manhood index for programmers" (if they are men) - translated to PT this would translate to "Índice de Macheza do Pugramador" (sic). And this is why: A man should only be considered a man if it is programming on its current position using one of the top 3 languages in this index. If not, you can say to you (man) colleague: "Ah, you're really a chicken" (or something alike, preferably equally insulting).

Talking more seriously, you can look at this index in several ways:
- The current month rank: Shows what languages are more popular (or at least what have been more researched upon)
- The recent years trend (since June 2001)

You can look at this index in several ways: I want to position myself in a "popular" language (which translates to "top ranking language" in this ranking) over the last few years (define the number of years for your particular case); this could be a wise career decision (medium-long term).

But don't forget to look it the other way (the short term): Older languages (like COBOL or Delphi / Object Pascal) are not so popular but because resources are scarce they will be highly paid and could be in high demand: For instance look for job positions of Delphi Programmers in the UK to sort it out (is 320 GBP a day good enough for you?).

sexta-feira, 13 de maio de 2016

BOOK: The Unified Modeling Language Reference (Booch, Jacobson, Runbaugh)

This is the total opposite of the UML Distilled book, mainly because it has ~700 pages.
It is still a very good book by Grady Booch, James Runbaugh and Ivar Jacobson.

http://www.amazon.com/Unified-Modeling-Language-Reference-paperback/dp/032171895X

Book additional details:
ISBN-13: 978-0321718952
ISBN-10: 032171895X

BOOK: Service Design Patterns: Fundamental Design Solutions for SOAP/WSDL and RESTful Web Services (Robert Daigneau)

On patterns related to Web Services (SOAP and REST):

http://www.amazon.com/Service-Design-Patterns-Fundamental-Solutions/dp/032154420X/ref=pd_sim_sbs_14_5?ie=UTF8&dpID=41A7b4McRzL&dpSrc=sims&preST=_AC_UL320_SR240%2C320_&refRID=1KKZFGSE9M8CEDJ03BNB

Quoting:
"Web services have been used for many years. In this time, developers and architects have encountered a number of recurring design challenges related to their usage, and have learned that certain service design approaches work better than others to solve certain problems. (...)

This book will help readers answer the following questions:

How do you create a web service API, what are the common API styles, and when should a particular style be used?
How can clients and web services communicate, and what are the foundations for creating complex conversations in which multiple parties exchange data over extended periods of time?
What are the options for implementing web service logic, and when should a particular approach be used?
How can clients become less coupled to the underlying systems used by a service?
How can information about a web service be discovered?
How can generic functions like authentication, validation, caching, and logging be supported on the client or service?
What changes to a service cause clients to break?
What are the common ways to version a service? How can web services be designed to support the continuing evolution of business logic without forcing clients to constantly upgrade?"

BOOK: Patterns of Enterprise Application Architecture (Fowler)

For Enterprise Design Patterns this book is a must:

http://www.amazon.com/Patterns-Enterprise-Application-Architecture-Martin/dp/0321127420/ref=pd_bxgy_14_img_3?ie=UTF8&refRID=03P48V22NYWE65KC0NV4

Citando:
"The practice of enterprise application development has benefited from the emergence of many new enabling technologies. Multi-tiered object-oriented platforms, such as Java and .NET, have become commonplace. These new tools and technologies are capable of building powerful applications, but they are not easily implemented. Common failures in enterprise applications often occur because their developers do not understand the architectural lessons that experienced object developers have learned. (...)

The topics covered include

· Dividing an enterprise application into layers
· The major approaches to organizing business logic
· An in-depth treatment of mapping between objects and relational databases
· Using Model-View-Controller to organize a Web presentation
· Handling concurrency for data that spans multiple transactions
· Designing distributed object interfaces"

BOOK: Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions (Woolf / Hohpe; 2003)

For successful integration of several information systems and/or data the use of enterprise integration patterns will help for sure:

Systems Modeling: About SysML

About SysML, a Systems Engineering Modeling Language, based on UML and using the UML Profile mechanism (that allows it to be extended):

http://www.omgsysml.org/INCOSE-OMGSysML-Tutorial-Final-090901.pdf
https://en.wikipedia.org/wiki/Systems_Modeling_Language#List_of_SysML_Tools
http://www.jot.fm/issues/issue_2007_07/article5.pdf - 155 pages overview
http://www.informit.com/store/sysml-distilled-a-brief-guide-to-the-systems-modeling-9780321927866 - SysML Distilled BOOK in a format similar to the UML Distilled book.

PS. Sparx EA tool does support SysML.

quinta-feira, 12 de maio de 2016

What's Fault Injection? And more...

What is fault injection, and why are we talking of it here around? The answer lies at the end. As usual. You shouldn't just look at the "trailer".

Some info on fault injection can be found here:

Why do some (weird) people inject faults: http://dl.acm.org/citation.cfm?id=272273 (paper by J. Carreira, J. Gabriel Silva)
https://en.wikipedia.org/wiki/Fault_injection
Hardware and Software Fault Injection: http://www.cs.umd.edu/~atif/Teaching/Fall2009/Jonathan.pdf (mentions Xception - used by NASA JPL, Jaxa and other space organizations and made by a portuguese company you might have heard of).

Fault injection products and more about a specific one (Xception):

http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.23.4724&rep=rep1&type=pdf - powerpoint mentioning Xception
https://www.cisuc.uc.pt/publication/show/978 - a paper on Xception, by guess who? (*)
About Xception, as published on IEEE:

An important step in the development of dependable systems is the validation of their fault tolerance properties. Fault injection has been widely used for this purpose, however with the rapid increase in processor complexity, traditional techniques are also increasingly more difficult to apply. This paper presents a new software-implemented fault injection and monitoring environment, called Xception, which is targeted at modern and complex processors. Xception uses the advanced debugging and performance monitoring features existing in most modern processors to inject quite realistic faults by software, and to monitor the activation of the faults and their impact on the target system behavior in detail. Faults are injected with minimum interference with the target application. The target application is not modified, no software traps are inserted, and it is not necessary to execute the target application in special trace mode (the application is executed at full speed). Xception provides a comprehensive set of fault triggers, including spatial and temporal fault triggers, and triggers related to the manipulation of data in memory. Faults injected by Xception can affect any process running on the target system (including the kernel), and it is possible to inject faults in applications for which the source code is not available. Experimental, results are presented to demonstrate the accuracy and potential of Xception in the evaluation of the dependability properties of the complex computer systems available nowadays
(Source: IEEE Transactions on Software Engineering - Volume:24 , Issue: 2; Feb. 1998)

The main reason I'm bringing this to your attention is just to remind you that you should always be with "eyes wide opened" regarding niches. 18 years ago this was a niche market (and it probably still is). It paved the way to a multi-million dollar company that you might be aware of. Will you be able to find yours? How are you planning to make a difference?

(*) One of these persons was a CEO of that company (João Carreira). The other one is the Principal of one of the oldest universities in the world (725 years on): João Gabriel. Henrique Madeira has had several important roles in that same university (as well as Gonçalo Quadros which was a teacher there). I was privileged to watch and participate in the journey from the inside and from the very start and I can say that I pretty much happy with it, so this is the story so far.

(@2016-07-19: Added the "weird" paper; 2016-09-29: minor improvements/rephrases)

BOOK: Design Patterns: Elements of Reusable Object-Oriented Software (Gamma et al)

This is a must-read book aka as the Bible for Design Patterns written by the Gang of Four (GoF: Gamma et al.).

The main con is that examples are not in C# or Java (C++ and Smalltalk is used) but most of the design patterns introduced there are still widely used today.

Details here.

About QMS Process Areas, Documentation Levels and the Software Development Process (SDP)

The Short Story

The Top Level Docs of a QMS, e.g. the QM
How to subdivide Areas into Process Areas? By defining Key Process Areas in a QMS (acc. ISO15504 for instance). Details about Process Areas.
Documentation levels: QMS artifacts range from the top-level ones (referred above) to the more detailed ones. How could documentation levels be defined?
And last but not least: How to define your SDP?

The Long Story...

... Can be read following the above links and reading the SDP process document.

Defining your SDP

When defining your Software Development Process (SDP) where should you start?

First of all, if you can, don't define it. But most of the times you'll have to (to introduce your company's specifics and to allow for easier alignment of large teams).

So where should you start? From scratch?
No, it is suggested that you find whatever the industry states regarding the processes you are interested in and build upon it, using these standards as Reference Documents.

E.g.: If you're working for space, does it make sense to build your own SDP from scratch? Absolutely not. Above all, companies working on such mature markets will have to comply to standards, and some of those standards are related to software development, so you should start using them.
It'll save you time getting certifications, being certified by suppliers that might want to check how do you develop software (and perform other types of activities such as project management) before hiring you, etc.

So, you should definitely start by reading, understanding and using things like:

- ECSS (ESA standards), NASA-SEL (NASA standards): http://silvaonsoftware.blogspot.pt/2016/05/the-beauty-of-standards-and-more.html

For life cycles you have ISO 12207: http://silvaonsoftware.blogspot.pt/2016/04/standard-isoiec-12207-systems-and.html

For tailoring you have CMU/SEI-94-TR-024 and more: http://silvaonsoftware.blogspot.pt/2016/05/tailoring-in-your-sdp.html

For terminology you have also additional standards: http://silvaonsoftware.blogspot.pt/2016/05/standards-terminology-standards.html

So, for all reasons in the world you'll be doing... REUSE.

Key Process Areas in your QMS (ISO 15504, ISO 12207)

In a QMS several types of processes will be needed in order to accomplish your work.

For a software development company, lots of core processes will be defined (engineering ones) but they are not enough. In the end you'll end with dozens of processes so it's a good idea to organize them in order to allow for some roles (e.g. engineers, project managers) not to get lost while starting.

So, one of the main issues here is how to do this split between them? Again the main keyword is REUSE. Let's not invent the wheel.

The key process areas in a Quality Management System can be based on the ISO15504/SPICE process model as well as the ISO12207 Life Cycle Model standards.

According to SPiCE for SPACE (ISO/IEC TR 15504 Conformant Method for the Assessment of Space Software Processes - Part A: SPiCE for SPACE Assessment Model, Issue 1.1 Draft C, 27.07.01, PASCON/WO6-CCN5/TN7A.) the following description is provided for each dimension:

Primary life cycle processes, includes customer-supplier processes and engineering processes. Customer-supplier processes have directly impact on the customer, support development and transition of the software to the customer, and provide for the correct operation and use of the software product and/or service. Engineering processes consists of processes that directly specify, implement, or maintain the software product, its relation to the system, and its customer documentation. In circumstances where the system is composed totally of software, the engineering processes deal only with the construction and maintenance of such software.

Supporting life cycle processes, includes processes that may be employed by any of the other processes (including other supporting processes) at various points in the software life cycle.

Organisation life cycle processes, includes management and organisation processes. Management processes contain practices of a generic nature that may be used by anyone who manages any type of project or process within a software life cycle. Organisation processes establish the business goals of the organisation and manage process, product, and resource assets that, when used by the projects in the organisation, will help the organisation achieve its business goals.

SW Design, SW Construction: Security as a Design Quality Attribute ("5 lines" summary)

Some topics on Security (the "5 lines" summary with a little bit more than 5 lines): As a systems analyst, system architect, software developer and tester (SPA Engineer) you must:

- Read on security related to the technologies you'll be using for producing the final information system being developed (i.e. the solution):

C++, C, Java, ... - there are full books on the security topic
JEE, .Net and other enterprise application frameworks
RDBMS and other entity persistence means
Other common core system components like...

App. Servers (JBoss and the like)
Web Servers (Apache, IIS and the like)

Operating Systems
Anything else (that your system reuses: drivers, hardware, ...).

- Make sure everything above is patched (regularly) and that whatever you program (and configure) is secure in the light of what you (regularly) read.

Remember to:
- Subscribe newsletters on the topic (of follow the proper newfeeds / groups) to help you keeping updated
- Use the proper frameworks for helping you on security as a process, for example:

The OWASP Application Security Verification Standard (ASVS) Project provides a basis for testing web application technical security controls and also provides developers with a list of requirements for secure development.

- Use the proper tools to help you (executing security assessments) before release. Raise all relevant [code] issues found.
- Reuse the invaluable resources (with guidelines and concrete checklists for specific technologies) like the following (take your time exploring them properly and use whatever suits you):

The bottom line:
Security is a process: You change a line of code (or a system component) and you could have changed the security characteristics of your system as a whole. Remember that a system is as strong as its weakest link (and you don't want to have been working on that weakest part).

(@2016-11-15: minor rephrases, formatting)

quarta-feira, 11 de maio de 2016

Standards: Terminology Standards (Acronyms and Definitions "for all")

Your company has for sure a Glossary of terms that you should read and know from the start to the very end. Do you?

If not, you can always start learning a little bit more about terminology of the [software] industry (as well as UXD terms and other related disciplines) in these standards and/or googable / purchasable documents:

ECSS, Glossary of Terms, ECSS-P-001 Issue 1 Rev., 11 June 1997. ECSS-P-001
ISO, Space systems. Glossary of terms, BS EN 13701:2001, CU, 15 July 2001 BS EN 13701:2001
CMU/SEI, CMMI for Development, CMU/SEI-2006-TR-008, Version 1.2., August 2006, CMU/SEI-2006-TR-008
ISO, Quality management systems. Fundamentals and vocabulary, BS EN ISO 9000:2005, October 2005, BS EN ISO 9000:2005

ECSS, Space Engineering – Software, ECSS-E-40B Draft 1, 15 February 2002. ECSS-E-40B
NATO, NATO Supplementary Software Quality Assurance Requirements to AQAP 2110, AQAP-2210 NATO, Edition 1 – November 2006, AQAP-150
NATO, NATO Quality Assurance Requirements for Design, Development and Production, AQAP-2110 NATO, Edition 3 –November 2009, AQAP-2110
SynSpace, Software Engineering Glossary, www.synspace.com, N/A

ISO, Human-centred design processes for interactive systems, 13407:1999, 1st June 1999. ISO13407:1999 (now outdated)
Morgan Kaufmann, Usability Engineering, Jakob Nielsen, 23rd September 1993. 978-0125184069
IS/ISO, Quality Management – Customer Satisfaction – Guidelines for Complaints handling in Organizations, ISO 10002 (2004), January 2006, ISO 10002:2004

(2016-09-30: reordering)

The Fun Dept.: The new password policy | Dilbert

PS. Copyright stated in the target image.

terça-feira, 10 de maio de 2016

INTERNAL RESOURCE: Toolsets and corporate info repositories

As you might notice the subtitles are somewhat disputable. JIRA was once just an issue tracker, now it's much more than this. So how would you categorize it? It's what it is. ;)

Installable Tools

- Install GTM locally (to attend GTM meetings): http://support.citrixonline.com/en_US/Meeting/help_files/G2M010002
- Install GTM Outlook Plugin (that adds some actions in the New Appointment window) - to speed up the schedule of meetings: https://builds.citrixonlinecdn.com/builds/calendarintegration/outlook/G2M/setup.exe

- EA: Download and install instructions (shared key):
https://delivery.critical.pt/TechAreas/net/SitePages/ToolEnterpriseArchitect.aspx
https://delivery.critical.pt/TechAreas/net/Shared%20Documents/Get%20shared%20Key%20in%20EA.PDF (Get Shared Key - Floating License).

Training and other "Knowledge Items" and Information Repositories

- Internal Training Materials (Recent):
https://my.critical.pt/humanresources/Pages/TRAINING-MATERIALS.aspx#Tools

- CMS - Technical Portal:
https://delivery.critical.pt/TechAreas/SitePages/Landing%20Page.aspx (Java, .Net, DB, UXD, Safety-Critical, etc.)
https://delivery.critical.pt/TechAreas/SafetyCritical/SitePages/Home.aspx

PS. Old portal in oldportal.critical.pt (https://oldportal.critical.pt/Paginas/Default.aspx)

- QMS Portal:
https://quality.critical.pt/

- QMS offline / RSS notifications HOWTO:
https://quality.critical.pt/SitePages/QMS/QMS%20Tutorial.aspx

- QMS Org. Stds.:
https://quality.critical.pt/orgstandards/Forms/QMS.aspx

Advanced Lifecycle Management (ALM) Tools

There are complete suites for advanced life-cycle management (ALM) of the software development (there is a list here) and some advanced editions of your favorite IDE could offer most of the ALM tools needed for demanding collaborative software development projects (in a single environment).
Also make sure to look here for the Gartner Magic Quadrant for the ALM Tools.

JIRA, JIRA plugins and Maybe More

If you do have the money, you could use a set of tools to support your software development. Some of them are free (as all good things in life). Some other aren't.

Examples include:

Issue tracker: Issues trend, tasks / actions management, risks, agile and crucible plugins, searches (by ID and custom searches), custom dashboards and exports.
JIRA Agile (previously called GreenHoper plugin, now comes out-of-the-box): burn-down charts, task boards, planning boards, etc.: https://jira.critical.pt/browse/VISIONCENTER/?selectedTab=com.pyxis.greenhopper.jira:greenhopper-project-panel-tab
Code Reviews plugin: Crucible: https://crucible.critical.pt/cru/ATG-5#CFR-11408
Test Management plugin: X-Ray, https://jira.critical.pt/browse/BFAFREND/?selectedTab=com.xpandit.plugins.xray:test-panel (also check BMS, NEO)
About X-Ray (and SPIRA): https://my.critical.pt/humanresources/Documents/CSW-SPA-2015-PRS-01762-test-management-with-xray.pptx
Risk Mg. plugin (Example): https://jira.critical.pt/browse/VISIONCENTER/?selectedTab=com.ja.jira.plugin.report.riskmanagement:RiskManagementTab

AOB

WISE: WISE Tasks (incl. recursivity); WISE Intra Doc (Doc. ID generation), WISE | Resources | Software Licenses, Lessons Learned DB; for PMs the Projects Module is the key feature (showing EVM indicators and more). Bein g phased out to other INTERNAL system: https://pulsar.critical.pt.
Task tracker for WISE (auxiliary tool, unsupported and being "phased out"): Accessible via the Intranet Tools menu. Stopwatch-like interface, useful for whoever has lots of WPs or Activities and has to record effort on them frequently: http://infoserv.critical.pt/index.php?title=Internal_Tools/Task_Tracker_for_Wise_%2B%2B/Releases

- Continuous Integration, examples:

Jenkins: http://jenkins.critical.pt/computer/(master)/
Teamcity could also be in use for some projects.
About CI: https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software

- Corporate site, Quality Certifications rationale:

http://www.criticalsoftware.com/pt/homepage (for the offer, verticals / business areas)
http://www.criticalsoftware.com/en/how-we-do-it/quality (look for "CERTIFICATIONS & STANDARDS")

- E-mail configs and list management tool (post 2016-05), CSW PT credentials:

List Management Tool (Local installation): \\files.critical.pt\Repository\Licensed-Software\CJWDe
Web mail: http://outlook.com/owa/criticalsoftware.com (redirected from https://mail.critical.pt)
Exchange config: http://www.colorado.edu/oit/tutorial/office-365-outlook-windows-manual-exchange-configuration
Mobile devices config: https://support.office.com/en-us/article/Set-up-Office-apps-and-email-on-a-mobile-device-7dabb6cb-0046-40b6-81fe-767e0b1f014f?ui=en-US&rs=en-US&ad=US
Office Online, Office 365 (for those who have license for it): https://login.microsoftonline.com

- VCS clients (INTERNAL):

CVS Windows client installer, get it here (or get TortoiseCVS): \\files.critical.pt\repository\Base-Software\CVS (see CSW-SYSDEPAR-2006-MMO-2514 for Windows, see CSW-SYSDEPAR-2006-MMO-2513 for Linux)
SVN Windows client installer (TortoiseSVN): \\files.critical.pt\repository\Base-Software\SVN
Git: Read this topic "Come on be a Git" for installers.
Web clients (for quick access of single files on computers without the local VCS clients installed; VPN required): https://svn.critical.pt/svn/ and https://cvs.critical.pt/cgi-bin/cvsweb.cgi/

(2016-05-11: added ALM reference as well as ALM links; 2016-06-07: added list mg. tool; 2016-06-09: Office 365; 2016-09-26: minor rephrases, VCS info; 2017-05-04: rephrases, detail in topics, formatting issues, pulsar, git)

sexta-feira, 6 de maio de 2016

The beauty of standards (and more)

Ah! The beauty of [software engineering] standards... Software engineering standards come in all kinds of shapes and colors like Victoria's Secret bras... Some standards are new but there are also good old standards that stood the test of time. On the darker side, the "standards industry" is well... an industry. If I build a better standard, certification, etc. I am able to sell you standard documents, certifications, training programs for training tutors, training sessions for people on companies and so on.
Standards people are also strange people. They can gather all together in a 5 story building for several months in a row to discuss a certain rephrase to this section of the standard. I know a person that has its name in the DO-178C draft. Not me.

If you're into the software engineering scene, maybe you can find interesting to browse these 2 space software standards:

ESA: https://goo.gl/4Gzdtq (ECSS stands for European Comitee for Space Standardization - INTERNAL)
NASA: https://goo.gl/wzJ8XE (SEL stands for Software Engineering Lab - INTERNAL)

Happy "readings".

Software Design: Architecture Specification

Architecture Specification (activity) consists of mainly 3 sub-activities:

Define Meta-Architecture Options: Principles, Style, Key Mechanisms; also: select key technologies; specify architectural guidebooks and standards (or identify the external ones to be reused); key mechanisms: coupling control strategy (layers), OOP approach, n-tier approach, layer comm., authentication, authorization, data editing strat., data id. strat., error handling, etc.)
Define Conceptual Architecture: Partition of the system, allocate responsibilities; On some guidance on how to perform the partition of the system (into subsystems / modules) read more at: http://silvaonsoftware.blogspot.com/2016/05/software-design-design-principles-and.html
Define Logical Architecture: Model collaborations, design interfaces

Additional Info on the SW Design Process

The SW Design Process has these 3 main tasks:

Architectural Requirements Sub-Activity: Establish architectural relevant requirements - org./functional/non-functional - and this implies: Establish org. goals and constraints, review functional requirements (complement with use cases), review non-functional requirements (associate measurable qualities with use cases)
Architecture Specification Sub-Activity: (this topic)
Architecture Validation Sub-Activity: Includes Architecture Peer Reviews, Brainstorming Key Decisions, Reuse, Traceability Matrices.

Further information can be found on your "favorite QMS" and here:
Visual Architecting Process (Web version and PDF).

Software Design: Design Principles (and how they could help us in partitioning the system)

With a good decomposition (into modules and submodules):

The overall system Design is improved (anticipating and solving earlier performance or scalability bottlenecks, better preparation for change and evolution, etc.) and...
It is easier to maintain (Maintainability) as well as...
It easier to Develop (during the following activities of software construction: easier to split tasks between developers, easier to integrate new technologies and new team members, easier to forecast the impact of new requirements with good accuracy, etc.).

But how exactly should it be performed? For some principles, jump here (*).

CHANGE IS PART OF LIFE: So we should design systems that cope with it "elegantly"
- The customer can change it's mind
- The market needs can change during the project (with impact on our scope)
- We could have got requirements wrong and have the need to rework them (as well as all dependencies on them, etc.)
- Reused components could have to be replaced (due to lack of support, stability, etc.) along the way
- etc.

Modules

A module can be defined variously, but generally must be a component of a larger system, and operate within that system more or less independently from the operations of the other components of the system. A module is a subdivision of complexity that has evident benefits.

Decomposition Levels

The first partition shall be determined by selection or design of an Architectural Archetype (system type, e.g. Web App)

The archetype establishes tier and layer separation and, in the physical tier perspective, a clear and unavoidable packaging and coupling isolation criterion.

The archetype is a structural technical view of the solution regardless of business domain and particularities. As such, it is a very stable and reusable specification.

The archetype is also a technological determinant decision as it clearly points to the usage of specific technologies, frameworks, development environments, etc.

The second level partition shall address decomposition of the archetype’s parts into Package Components (UML Package Diagrams; package = namespaces that group classes and interfaces)

The Packaging Components represent the binary outputs of the solution (in .Net for instance these correspond to the .EXE and .DLL)

Their decomposition criteria are based on coupling, deployment and tier placement.

The Packaging Component represents a single reference point for the functionality and is an aggregation for further decomposition (Component).

The third level partition shall address decomposition of the Package Components into Components and Interfaces and establish third-party dependencies (reuse process) - UML Component Diagrams

Remember that Components may be nested into each other to produce sub-levels of decomposition and reduce complexity of the overviews.

This is a pure conceptual view that is not directly concerned with packaging and deployment.

This view is oriented by “information-hiding” in Parnas sense. The goal here is to represent the system with as few major concepts as possible. Of course each of those concepts may be further detailed (by sub-components) as needed.

The fourth level partition shall address Component decomposition in Classes - Detailed Design; physical data tables could be also modeled (it the system is database-oriented) and traced to classes.

All elements of the decomposition should trace to the upper level elements they are related to (traceability) in the analysis model.

Principles for module decomposition

Strong cohesion and loose coupling (goals to be achieved):

Cohesion is a measure of how strongly related and focused the responsibilities of a single module are. That is, how homogeneous and simple is the goal of a software module.

Coupling (or dependency) is the degree to which each program module depends on each other module.

Package Cohesion Principles: Classes are a necessary, but insufficient, means of organizing a design. The larger granularity of packages is needed to help bring order. But how do we choose which classes belong in which packages

Release Reuse Equivalency Principle: The granule of reuse is the granule of release (and that should be the package).

Common Closure Principle: Classes that change together, belong together.

Common Reuse Principle: Classes that aren’t reused together should not be grouped together.

Package Coupling Principles: Applications tend to be large networks of interrelated packages. The rules that govern these interrelationship are some of the most important rules in object oriented architecture

Acyclic Dependencies Principle: The dependencies between packages must not form cycles.

Stable Dependencies Principle: Depend in the direction of stability.

Stable Abstractions Principle: Stable packages should be abstract packages.

Architectural Principles

Abstraction gears towards comprehension
Encapsulation gears towards protection from outside interference
Information Hiding gears towards containment of design changes
Open Closed Principle – OCP: “A module should be open for extension but closed for modification.” i.e. “We should write our modules so that they can be extended, without requiring them to be modified. In other words, we want to be able to change what the modules do, without changing the source code of the modules.”
Inversion of Control (or Dependency Inversion Principle) is an important object-oriented programming principle that can be used to reduce coupling inherent in computer programs: “Depend upon Abstractions. Do not depend upon concretions.” [Martin]
Interface Segregation Principle – ISP: “Many client specific interfaces are better than one general purpose interface” i.e. “If you have a class that has several clients, rather than loading the class with all the methods that the clients need, create specific interfaces for each client and multiply inherit them into the class.” [Martin]

Along with OOP Principles, some Design Patterns (which is a well known, very good solution for a recurrent problem) are also very useful while performing the decomposition of a system.

(*) Additional References and Further Reading

http://ifacethoughts.net/2006/03/24/design-principles/ (REP, DBC, etc.)
http://ifacethoughts.net/2006/04/04/reuserelease-equivalency-principle/ (REP)
https://sourcemaking.com/design_patterns (Design Patterns: structural and more - creational and behavioral; also remember to avoid anti-patterns)
https://sourcemaking.com/refactoring (code smells: what to do to improve this "code smell"?)
Design Principles and Design Patterns - Robert C. Martin - 2000
OOP principles (if you're using OO Languages): Abstraction, Encapsulation, Information Hiding
Additional Source: ITG M. and Uncle Google giving us the above cited results.

Also remember to learn - at a second stage - about:

Database Design Patterns,
GUI Design Patterns (and UXD - User interaction),
Enterprise Architecture Patterns (Integration),
etc.

(2016-05-12: Added link for enterprise integration patterns; 2016-07-21: formatting, typos)

What does Victoria's Secret has to do with Software Engineering?

Ah well, in fact nothing at all (*).

And no, this link did not lead you to the "soft porn" site https://www.victoriassecret.com/ (I'm kidding, it's a bra well known and reputed e-commerce site). But the next one will (I was just double-checking).

(*) We could be discussing the design of the site, the overall architecture and its quality attributes (of the site, I mean), for instance, performance, scalability, maintainability, supportability, etc, but... No really.

(2016-07-28: Updated to include this very well designed site: https://womensecret.com/pt/en/homepage; no links, we don't want to be indexed for the wrong reasons)

quinta-feira, 5 de maio de 2016

INTERNAL RESOURCE: O "caminho da felicidade" (aka as The Roadmap)

"O caminho da felicidade" (which means "The Road to Happiness") is not this one but this is the path we've been through the training problem, sorry, program:

https://moodle.critical.pt/moodle/file.php/530/ITGROW-2010-PRS-00021-module-1-introduction.pptx - The problem, sorry program introduction. Who am I? Where am I? What is the meaning of life? (A: It's a Monty Python film, sponsored by Beatle George Harrison BTW)
https://moodle.critical.pt/moodle/file.php/530/ITGROW-2010-PRS-00023-module-3.a-software-development-process_SDP_-waterfall-and-scrum.pptx - The Marine One Helicopter view of 2 methodologies that your company should be using to do... Software?
https://quality.critical.pt/QMS%20PT/SUP-support/SUP-01-documentation/CSW-QMS-2002-GLS-0353-glossary.pdf#search=glossary - The Glossary (includes SW Eng. acronyms and definitions and more) based on industry standards for that purpose (surprise!); docs scanned: SDP, PLC, GLS, Master Template (Word Fields, F9, Shift F9)
Scrum Official Guide (and the Agile Manifesto) - The "bible" to agile/scrum in 16 pages by "Jesus and Mary" (the original authors) - find them (as well as a "5 line" summary) here (Update: Now there is a 2016 version, look here for the differences)
https://moodle.critical.pt/moodle/file.php/530/ITGROW-2011-PRS-00003-module-6-eng-1-requirements-analysis.pptx - The QMS process (and related issues) used for gathering requirements in the proper phase. If this phase / process stuff confuses you, read this.
https://moodle.critical.pt/moodle/file.php/530/ITGROW-2011-PRS-00014-module-7-eng-2-software-design.pptx - The QMS process being used for doing High Level Architectures, Detailed Design and more.
https://moodle.critical.pt/moodle/file.php/530/ITGROW-2011-PRS-00015-module-8-eng-3-software-construction.pptx - The QMS process for coding i.e. software construction (according to the requirements and the design); bottom-up estimation, static analysis, code reviews (arrrrgh?...).
https://moodle.critical.pt/moodle/file.php/530/ITGROW-2011-PRS-00031-module-10-eng-4-software-testing-process.pptx - The QMS process used for Verification and Validation (remember, doc reviews, code reviews are verification measures)
https://moodle.critical.pt/moodle/file.php/530/ITGROW-2011-PRS-00028-module-9-eng-4-software-testing.pptx - The developer's perspective, covering unit testing, data-driven testing and a little bit more. Written by a "programmer" (this is a private joke, since if the author knew I called him this, he'd kill me ;).
https://moodle.critical.pt/moodle/file.php/530/ITGROW-2011-PRS-00001-module-5-modelling.pptx: What's this modeling, analysis model and related stuff all about? What's a modeling tool? Modeling challenges. Generating documentation from the model.

Also remember that Module 8 has illustrative examples on when and how to use the modeling tool for reverse engineering (code, data model; section 8.3 p.e.) and possible detailed design (SDD) automated generation (even if partially).

Additional information (Google for it or use the provided links - some are INTERNAL):

EA UML modelling tool Reviewer's Guide: Look here.
UML Distilled (book)
Writing good requirements (topics: books, papers, etc.): Example of a paper here.
Estimation (bottom-up and more): Look here (training materials) and in the process.
Visual Architecting Process: Look here and PDF version here.
Design patterns: Look at this Wikipedia link and use the books of the GoF as well as Code Complete 2. Another interesting resource is sourcemaking.com (Design Patterns, Anti-Patterns and Refactoring / Code Smells).
Performance (and architecture that drives this performance): http://www.javaperformancetuning.com/
Static Analysis: Look here about one multi-language static analyzer Source Monitor.
Code Reviews: Review Procedure here; Crucible Tool GBK here; CheckStyle (Java) tool GBK here.
Continuous Integration: Look here.
EA12 - EA13 UML tool commands mapping here.
Terminology standards (definitions and acronyms): Look here (for a glossary and some relevant standards).

PS. As you might already know, all materials are here (INTERNAL).

PS2. BTW do you know what is figuratively meant by "O caminho da felicidade"? ~~The first one who answers correctly will earn a bunch of beers at the usual binge drinking place around (CBR). You know my name, look up the number (this is a song by The Beatles)~~.

(@2016-05-10: Additional links; 2016-05-11. Added GLS, terminology stds.; estimation PPT; 2016-05-12: Add. links to the Add. info section; 2016-05-18: QMS docs to scan; 2016-05-24: Added reverse details, GLS terminology std.s link; 2016-07-14: July 2016 Scrum Official Guide reference; 2016-07-21: additional links; 2016-07-28: JPT , good req.s links; 2017-12-19: EA13 commands mapping added)

Scrum (Agile) main documents and the 5 line summary (or not)

Scrum main documents include:
- The Agile Manifesto: the rationale behind scrum agile methodology.
- The Scrum Official Guide: maintained by the 2 framework authors up until... today (July 2013 version here).

The guide describes in merely 16 pages (!) a "new" ground-breaking framework for [software] product development. I give you the "5 lines" summary (as if it was needed):

Pillars:

Transparency (progress towards the Sprint Goal; definition of Ready is a transparency measure also)
Inspection: several opportunities for inspection (events, etc), but not so many that gets in the way (of reaching the sprint goal)
Adaption: if something is found it shall be fixed (or annotated as technical debt)

Roles:

PO (the owner of the product backlog; one person not a committee); can delegate but is still owner,
SM (the facilitator; ensures scrum is understood; services to the PO, to the Dev. Team and to the Organization),
Development Team (cross-functional, please; self-organizing - SM does not need to tell what's next): 3 to 9.

Events: All time-boxed (fixed max. duration)

The Sprint; fixed duration (fixed team); could be cancelled (if the sprint goal does not make sense anymore); max. 4 weeks.; if cancelled, Done items shall be reviewed all the same (by the PO)
[Sprint] Planning: all team; choose "Ready" items from the PBL to the Sprint BL (after defining and having the Sprint Goal defined; do not choose non-ready items. Leave unplanned buffer (%); use sprint velocity from previous sprints (team DOES not change and is allocated 100%; what to do next sprint and part 2: how to do (technical aspects included); time-boxed to 8h (1 mth sprint), proportionally smaller for smaller sprints.
Daily Meeting: 15 mins, SM and Dev. Team; if SM is not present shall delegate; optional: SM presents team progress (burndown chart) at start; each developer: what I've done, what I'll do today; what is blocking me (to be solved in 1-2 mins or at a tech meeting with relevant stakeholders afterwards); stand-up meeting.
[Sprint] Review: all team; review US definition (including Acc. Criteria) and demonstrate that it is Done. present all "Done" US to the PO. Answer questions, interact with the software, inspect results, answer to questions. Rework could be raised - as new US (even if the story is Accepted - changed to the Closed status by the PO ideally); time-boxed to 4h (1 mth sprint).
Retrospective: All team (w/o PO); think of lessons learned; what to start doing, stop doing (think on people, relationships, process, and tools); raise actions to fix (or study the); provide status of previous actions until closure; remember to plan for those actions to be closed also in Sprint Planning; time-boxed to 3h (1 mth sprint).
NOT AN EVENT: Refinement, Backlog Grooming, Pre-planning meetings: Prepare US to be "Ready" (PO, SM & parts of Team); convert Epics (Themes, high level features) to "Ready" US; use planning poker estimation technique; each and every US shall respect the INVEST model.
Planning poker estimation technique: estimate story points - cards deck or mobile app
Definition of "Done": Transparency; informal: Definition of "Ready". All tasks that should be completed before some US can be stated at that status.
Events sequence for 2 wk sprint: Planning, Daily(ies), Pre-Planning (several meetings, second week), Review (Demo, last 1-2 days); Retro: after Review (friday).

2 Artifacts:

PBL: Contains PBI: Epics / Themes, User Stories (Drafts, Ready), other tasks (setup, documentation, ...): owned by the PO (which can delegate); is an ordered list (by priorities, at least for the items for next sprints)
Sprint BL: Contains Ready US chosen from the PBL to fulfill the Sprint Goal + other tasks (unplanned, research spikes, technical debt, other tasks such as technical documentation tasks - not to be delivered in the increment - , etc.); the potentially shippable product increment contains the "Done" US (only those approved by PO)

AOB:

Research spike; technical debt; pigs and chicken, potentially shippable product increment = increment = something that can be incorporated in the shipped product.
Burndown chart (personal and for the team): Ideal curve; Are we late? How many (hours, US) do we need to do to converge to ideal curve; estimation accuracy; important for self-control. Important to report effort daily.
Taskboard: Ready - In Progress - Done - Closed / Reviewed (use post its on the wall if no IS is available)
Tools to support: dash boards for auto-control; task board; storage for US; issue tracker (for other tasks/actions).

More interesting resources include:
- Scrum Glossary: https://www.scrum.org/Resources/Scrum-Glossary
- Resources: https://www.scrum.org/Resources

(2016-06-06: add. links at end)

quarta-feira, 4 de maio de 2016

TOOLS: Continuous Integration Servers (List)

Unsurprisingly enough, a list (with several issues, but still very informative) of several Continuous Integration Servers can be found here:

https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software

PS. If in doubt, you wouldn't go wrong with TeamCity or Hudson.

TOOLS: Static Analysis Tools (Listing)

A good list of static analysis tools can be found here (please remember to look at the references section):

https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis

IDEs

Also remember that your favorite IDE might already have something in this field (either natively or via plugins) and that you might be more productive working in an integrated way (when doing self-control of the quality of what you are producing while coding).

CI and Static Analysis Tools

For CI it will be important that a command line utility exists (so that one of the integration tasks could be like "generating static analysis reports for the build") and that it generates parseable results (XML, html, text files; so that a build could be set to fail if a certain Code Metrics mandatory rule is being broken).

PS. Remember, for some safety-critical projects, the standards you have to work against to will mandate that the produced code respects some very specific rules (e.g. regarding cyclomatic complexity, simply because this code is much harder to verify and validate than simpler code).

TOOLS: Source Monitor (Static Analysis - Multi-language)

Static analysis refers to analysis of the code statically (without running it).
There are several tools embedded in modern IDEs (as plugins or even natively).
There are also some standalone multi-language tools.
A simple (and free) example of a tool like this is the multi-language tool named Source Monitor:

http://www.campwoodsw.com/sourcemonitor.html

Quoting:
"The freeware program SourceMonitor lets you see inside your software source code to find out how much code you have and to identify the relative complexity of your modules. For example, you can use SourceMonitor to identify the code that is most likely to contain defects and thus warrants formal review. SourceMonitor, written in C++, runs through your code at high speed, typically at least 10,000 lines of code per second. SourceMonitor provides the following:

Collects metrics in a fast, single pass through source files.
Measures metrics for source code written in C++, C, C#, VB.NET, Java, Delphi, Visual Basic (VB6) or HTML.
Includes method and function level metrics for C++, C, C#, VB.NET, Java, and Delphi.
Offers Modified Complexity metric option.
Saves metrics in checkpoints for comparison during software development projects.
Displays and prints metrics in tables and charts, including Kiviat diagrams.
Operates within a standard Windows GUI or inside your scripts using XML command files.
Exports metrics to XML or CSV (comma-separated-value) files for further processing with other tools."

What do you do static analysis for?
Some reasons include:
- For quickly gaining insight on some new code (to you) when entering a project
- For spotting difficult parts of the code (in terms of complexity for example), spotting refactoring candidates
- For quickly analysing some quality attributes of the code being produced by the team (as a Technical Manager or mini-team leader, for instance % of comments when compared to LOC)
- For presenting reports to the customer on specific quality attributes of the code (Kiviat Charts with KPIs and an optimal region where we would like or are obliged to have the code).

History: Added details, quote 2017-11; 2017-12-04: Minor rephrases;

BOOK: Must have Microsoft Press books on Software Engineering

You may like or not like Microsoft.

Microsoft Press has books on Microsoft technologies but has loads of books on Software Engineering (the topic of this blog) like Steve McConnell's "Code Complete" and "Software Project Survival Guide" as well as "Software Requirements" and more, much more.

Sometimes they'll allow for free downloads here at this blog. Give it a look, periodically.

BOOK: UML Distilled (Martin Fowler)

This is my top recommendation for having on the desk, instead of the real UML standards (thousands of pages). If you're using UML to convey some design (or software construction) information, this book on its third edition provides you simple chapters with only a few pages per UML diagram type, speeding you up in understanding (and allowing you to create new) UML Diagrams.

Our (old) copy of the book

This and the cheat sheet (in the cover pages) makes this book a must have.
You can read more about it here:

http://www.amazon.com/UML-Distilled-Standard-Modeling-Language-ebook/dp/B000OZ0N8A/ref=sr_1_1?s=digital-text&ie=UTF8&qid=1462357802&sr=1-1&keywords=uml+distilled

From the Back Cover:

Would you like to understand the most important elements of Class diagrams? (See page 35.)
Do you want to see the new UML 2.0 interaction frame notation for adding control flow to sequence diagrams (see page 58) and the unofficial notation that many prefer? (See page 60.)
Do you want to know what changes have been made to all versions of the UML? (See page 151.)
Do you want a quick reference to the most useful parts of the UML notation? (See the inside covers.)
Do you want to find out what diagram types were added to the UML 2.0 without wading through the spec? (See page 11.)
More than 300,000 developers have benefited from past editions of UML Distilled . This third edition is the best resource for quick, no-nonsense insights into understanding and using UML 2.0 and prior versions of the UML.
Some readers will want to quickly get up to speed with the UML 2.0 and learn the essentials of the UML. Others will use this book as a handy, quick reference to the most common parts of the UML. The author delivers on both of these promises in a short, concise, and focused presentation.
This book describes all the major UML diagram types, what they're used for, and the basic notation involved in creating and deciphering them. These diagrams include class, sequence, object, package, deployment, use case, state machine, activity, communication, composite structure, component, interaction overview, and timing diagrams. The examples are clear and the explanations cut to the fundamental design logic.
If you are like most developers, you don't have time to keep up with all the new innovations in software engineering. This new edition of Fowler's classic work gets you acquainted with some of the best thinking about efficient object-oriented software design using the UML--in a convenient format that will be essential to anyone who designs software professionally.
About the Author
Martin Fowler is an independent consultant who has applied objects to pressing business problems for more than a decade. He has consulted on systems in fields such as health care, financial trading, and corporate finance. His clients include Chrysler, Citibank, UK National Health Service, Andersen Consulting, and Netscape Communications. In addition, Fowler is a regular speaker on objects, the Unified Modeling Language, and patterns.

(@2016-07-20: Cover photo and co-author)

BOOK: Code Complete (Steve McConnell)

Steve McConnell's Code Complete has been around helping developers building better software for a long time ago. Now on its second edition (Code Complete 2).

Quoting:
"Widely considered one of the best practical guides to programming, Steve McConnell’s original CODE COMPLETE has been helping developers write better software for more than a decade. Now this classic book has been fully updated and revised with leading-edge practices—and hundreds of new code samples—illustrating the art and science of software construction. Capturing the body of knowledge available from research, academia, and everyday commercial practice, McConnell synthesizes the most effective techniques and must-know principles into clear, pragmatic guidance. No matter what your experience level, development environment, or project size, this book will inform and stimulate your thinking—and help you build the highest quality code.
Discover the timeless techniques and strategies that help you:

Design for minimum complexity and maximum creativity
Reap the benefits of collaborative development
Apply defensive programming techniques to reduce and flush out errors
Exploit opportunities to refactor—or evolve—code, and do it safely
Use construction practices that are right-weight for your project
Debug problems quickly and effectively
Resolve critical construction issues early and correctly
Build quality into the beginning, middle, and end of your project"

Read all about it here: http://www.amazon.com/Code-Complete-Developer-Best-Practices-ebook/dp/B00JDMPOSY

(updated 2017-06-22: Back cover info)

terça-feira, 3 de maio de 2016

The Fun Dept.: The Dilbert Comic Strip

I thought everyone knew (and loved) Dilbert. When I am down and out, this is the comic strip that still can make me laugh. I share this out with you all because I found out I was wrong (i.e. some of you still don't know it).
The author (Scott Adams) worked lots of years in the "Corporate America" and so he knows very well how things go there. Also, he knows very well the product development / software development industry.

The comic strip is for free (and you can also buy the books on your favorite bookstore). You can sign for the daily dilbert here. And you can also follow the Blog.

Either way, the highlights could be something like:

Extreme Programming: http://dilbert.com/search_results?terms=extreme+programming
Project Management: http://dilbert.com/search_results?terms=project+management
Risk Management: http://dilbert.com/search_results?terms=risk+management
On Programmers: http://dilbert.com/search_results?terms=programmer
On testers and testing: http://dilbert.com/search_results?terms=tester, http://dilbert.com/search_results?terms=testing
On "overheads" like... Accountants and more: http://dilbert.com/search_results?terms=Finance%20Troll
On dinosaurs, like... Well paid COBOL programmers: http://dilbert.com/search_results?terms=Bob%20the%20Dinosaur
On Marketing people: http://dilbert.com/search_results?terms=marketing
And so on... You can also (and probably should) read the strips in chronological order (2016). The archive starts in... 1989.

(2016-05-04: Added more categories)

RESOURCE: Software Development Processes (Methodologies)

Some interesting Wikipedia articles and resources on software development methodologies include:

These include Waterfall (and the extension to it, called V-Model), Agile (including Scrum) and more:

Agile includes:

Lightweight methodologies include:

Make sure to also look and read some of the additional final references in the articles.

(@2016-05.25: updated tags, final rec.; similar article)

The Fun Dept.: BULLSHIT BINGO

Do you know bullshit bingo?

Learn about it here:

Tailoring in your SDP

Tailoring is a common term in software engineering. What is it good for? First we should try to explain what is this tailoring thing about i.e. introducing the terminology and the need for tailoring (no, it does not have to do with tailors - if you think that, then start by reading more about the subject - which could be the reason you got here).

Tailoring the Software Development Process

The QMS processes may be individually selected, tailored and even modified/extended, as necessary, to achieve the specific goals and requirements for a project. This is described in the Project Life Cycles document and in the level 2 documentation for each process (e.g. Requirements Analysis, Software Design, Software Construction, Software Testing, Maintenance, etc.).

Each level 2 process document contains a “Process Tailoring” section that presents approved tailoring
considerations relevant to each process. Additionally specific Pre-Tailoring Process Guidelines could already be defined for some specific types of projects.
For Example:
• Research & Development Projects Tailoring Guidebook;
• Maintenance Projects Tailoring Guidebook.

Additional info on tailoring can be found in the SDP (SDP-0909). Tailoring decisions are typically recorded in Quality Assurance Plans for the projects (QAP) and properly stored under version control.

How is it done in the "real world"?

For some software development processes the approach goes through a definition of project types (and the software life cycle under waterfall methodologies) and some well defined project attributes (like team size, project criticality, schedule aggressiveness, etc.) will allow you to REUSE a set of pre-tailored decisions (use this phase, do not use this phase, skip this milestone, deliver these deliverables, produce this documentation, perform these measures of verification and validation or not, etc.). The projects upon start can inherit these pre-tailoring decisions, and if needed (and justified) perform some more. Note: Sometimes the PM will have to approve further changes with the Quality Department. Some additional tailoring decisions are simply not acceptable, for instance: "Let's not do any documentation for this new software development project because we don't have resources for that".

Different projects lead to different needs. These project types are high-level taxonomic classes that, in the organization’s experience, lead to substantially different development scenarios and requirements. For instance: Software Development projects, Research and Development Projects, Maintenance Projects, Service Projects, Outsourcing Projects, etc.

Project Types and Project Attributes

The Project Types give us indications of particular project’s vulnerabilities (in the example more based in available knowledge and experience) that a more formal, frequent, granular or extensive process performance may help overcome.

The Project Attributes pinpoint project’s characteristics that advise a more strong or relaxed approach to process performance.

Notice that project attributes consideration may lead to different conclusions: A High Reuse project with a high level of Criticality shall enforce very formal and detailed verification and validation processes.

Tailoring targets

Tailoring targets are software development processes and activities. Its upon the software development process descriptions and requirements that tailoring activity will be exercised.

Classified a project, established its attributes and considered its tailoring factors this information shall be cross-related with the goals of each process and activity in the software development process and these processes and activities “tailored” to meet the goals of the project.

Tailoring activity may decide that a particular activity (or even a process) has no reason to exist in a project, in most of the cases however, it will be exercised what is known as “Tailoring by Degree”

Tailoring by degree

Tailoring by degree acts upon processes and activities attributes adjusting them to the needs and goals of a project.
Formality - the essential aspects of an activity can be performed with varying degree of detail, or attention to formal rules, procedures, or standards.(…)
Frequency – (…)The frequency of each activity needs to be interpreted in light of the organisation's and project's needs.
Granularity - the level of detail needed in the process definition may vary. (…) A project may want to include more or less detail (…).
Scope - it may not make sense to perform certain activities, due to organizational constraints, business environment, etc.

Source: Process Tailoring and the Software Capability Maturity Model – CMU/SEI-94-TR-024 – Mark P. Ginsberg, Lauren H. Quinn – 1995.

Sources (and further reading)

Process Tailoring and the Software Capability Maturity Model – CMU/SEI-94-TR-024 – Mark P. Ginsberg, Lauren H. Quinn – 1995

“Tailoring is a key element in the organization’s ability to develop reasonable and efficient software development plans for use in managing and controlling projects within the organization.”

A Matrix Approach to Software Process Definition – NASA SEL - David Schultz, Judith Bachman, Linda Landis (CSC), Mike Stark, Sally Godfrey (GSFC), Maurizio Morisio (Univ. of Maryland) - 2000 (pdf here)

“Tailoring is a process by which individual requirements or specifications, standards and related documents are evaluated and made applicable to a specific project, by selection and in some exceptional cases, modification of existing or addition of new requirements.”

ISO/IEC 12207 Systems and software engineering -- Software life cycle processes

Details elsewhere here. Quoting: "ISO/IEC 12207:2008 establishes a common framework for software life cycle processes, with well-defined terminology, that can be referenced by the software industry [It aims to be the standard that defines all the tasks required for developing and maintaining software]. It contains processes, activities, and tasks that are to be applied during the acquisition of a software product or service and during the supply, development, operation, maintenance and disposal of software products. Software includes the software portion of firmware."

(...) ISO/IEC 12207:2008 also provides a process that can be employed for defining, controlling, and improving software life cycle processes.

(2016-05-04: Minor rephrases; addit. hyperlinks)

The top-level docs of a QMS

The Short Story - Examples

The Long Story

Some typical top-level documents of a QMS include (documentation levels are described here):

The Quality Manual (Sometimes titled "Quality Management System" document or "Integrated Manual System" if if handles more than "just" quality issues)
The Software Development Process documentation (SDP and PLC).

Here are some of the documentation levels and some examples of documents on each level:

Level 0:

CSW-QMS-2004-CPD-0156 Quality Manual (or QMS, or IMS)

Level 1 (High-Level Processes):

CSW-QMS-2002-PCS-1475: Quality Management Process

CSW-QMS-2002-SDP-0909: Software Development Process

CSW-QMS-2003-PCS-2296: Project Life Cycle Management Process

CSW-QMS-2004-PCS-1608: Process Improvement Process

CSW-QMS-2009-PCS-04341: Project Management Process

(etc.)

Level 2: (etc.)

The Quality Manual

If the word quality means a thing for a certain organization it shall have a Quality Manual (QM), which states the company commitment to quality (and is required by most quality certifications).

The SDP (and its relation with the PLC)

If your company does software development, then it has a process (inputs: customer requirements, outputs: a working deployed solution). The typical name of this process is... Software Development Process or SDP. Typically this process will be written (*).

Your company could have a single SDP document for all software development methodologies that it plans to use, or - a better idea - can have several documents, one for each methodology (Waterfall, Agile - SCRUM, etc.).

For waterfall methodology: Sometimes some project types (that need to be typified concretely) do not need all the phases (and its related "overhead").

So, a project type list shall be done, and an adjusted software life cycle must be defined for that specific project. Some companies will have the general phases described in one document (the [waterfall] SDP) and those details - of what should and what should't be simplified - in another which could be called "Project Life Cycles" (PLC).

In fact this constitutes a pre-tailoring of the QMS processes to be applied to these project types (more on tailoring later on), speeding up project start.

(*) Is it always like this? Maybe not. For small teams, small projects (read: startups), things could succeed without strict process definitions (or by using agile methodologies).

(2016-05-04: Added short story, long story layout)

Key Process Areas in a QMS

Key Process Areas (Process Groups) are another way of partitioning and highlighting some processes over other.

Some international standards can be used for defining key process areas: The key process areas in the QMS are based on the ISO15504/SPICE process model and the ISO12207 Life Cycle Model standards.

A possible configuration for a QMS might have these definitions:

Primary Life Cycle processes

Technical processes performed by projects such as Software Requirements, Software Design. Software Construction, Software Testing, Maintenance and Support.

These comprise Customer (CUS) and Engineering (ENG) processes.

Supporting Processes

Performed in more than one Life Cycle stage, e.g. Configuration Management.

These comprise Support Processes (SUP).

Organisational Processes

Typically management-related processes, e.g. Project Management, Risk Management, Scope Management.
These comprise Organisational (ORG) and Management (MAN) processes.

In my company, as of today, there are hundreds of documents in the QMS and of those ~57 are process documents (level 2 documents, excluding the SDP which is by itself a process). So if I am a software engineer, it is for sure useful to know that the core engineering processes are marked as ENG.* (* means "something") and that these should be the first ones to read (and to get to know "back and forth"). SUP and MAN (Support and Management processes come after for sure, if I want to start accumulating a Configuration Management role in some project team or if I want to evolve to a project management career, for instance). In other words: It's easier to do what we should do in life: Which is TO FOCUS (*).

PS. For documentation levels see more info here.