Take Away: The term software artifact has a general meaning in software development process. Several processes have used this term as part of their process. This article focuses on both the general definition and a specific implementation in PSDP Online.
Do Prestwood Clients Need to know About Artifacts? As a Prestwood client, it's a good idea to understand PSDP and PSDP Online. This article discusses how we use PSDP Artifacts to build better software for you. If you have questions, please contact Mike Prestwood.
Developer's and Artifacts As a software developer, you should be familiar with software artifacts and how they're used within your process. Learning about PSDP Artifacts will help you decide how to do something similar in your process. If you're a Prestwood developer, you need to be familiar with PSDP Artifacts, how they are implemented in PSDP Online, and how they fit within your team's process.
The general meaning of the term software artifact is any nugget discovered and developed and used during software development and maintenance. In the general form, a software artifact can be pretty much anything! Examples are requirement items, design items, diagrams, test script, and even code itself. Within most processes, documents and other deliverables are frequently called software artifacts. In general, you could say, the artifacts of this process are x, y, and z.
UML Artifacts In UML 1.x, many UML users referred to the UML diagrams as UML Artifacts. Starting with UML 2.0, a UML Artifact is defined as a physical unit, such as an application executable, database, file, script, etc. Only artifacts live on physical nodes; classes and components do not have "location." However, I have seen many UML users still referring to UML Diagrams as UML Artifacts. Although I think this is very acceptable because of the generic definition of software artifacts, I would recommend against it now that UML Artifacts are defined in UML 2.0.
PSDP Artifacts vs. UML Artifacts - There is no real relation between these two items. A PSDP Artifact is used to solve a particular process problem. A UML Artifact is the result of that process.
RUP Artifacts The Rationale Unified Process (RUP) uses the term artifact in primarily in it's general form. For example, a RUP Artifact is sometimes defined as an input and/or an output to an activity. In the RUP PM discipline, artifacts are such things as the Software Development Plan, the Business Case, Iteration Plans, and Project Measurements.
SCRUM Artifacts Scrum also uses the term artifacts in a general form. The primary SCRUM Artifacts include the Product Backlog, the Sprint Backlog, and a Burndown Chart.
Product Backlog - a list of customer requirements prioritized by business value.
Sprint Backlog - a list of the specific development tasks required to implement a feature.
Burndown Chart - shows the cumulative work remaining in a Sprint, day-by-day. It is used as a tool to guide the development team to successful completion of a Sprint on time with working code that is potentially shippable as a product
Perhaps it doesn't need to be written, but, again, these artifacts have little to do with a PSDP Artifact.
A PSDP Artifact is a specific implementation of the idea of the generic software artifact. A PSDP Artifact is used to work with a software feature from inception through testing. It usually represents a documented and tested software feature such as a module, library, web page, form, or report.
The Problem In software development, it is a best practice to verify the finished product with the original requirements gathered at the beginning of the project. It is also a best practice to create test scripts that test the original requirements and for the design of the software to map in some way to them as well. These best practices imply a link between each requirement element, design element, and test script. Without a solid link, you are relying on the skillset of the team. With process you can decrease the ambiguity and stress of auto-magically matching up requirements with design and the testing of the software.
PSDP Artifacts Defined In PSDP Online, a PSDP Artifact links together a task, requirement item, design item, and test script all with the same name and associated with the same project category (if used), actors (if used), and project/application status. You can edit a PSDP artifact as a whole or expand any of the four linked items to include more details. This allows you to work with a feature from requirement through testing (we may add such things as user documentation to artifacts later).
PSDP Artifact Items Working with artifacts allows you to work with an application feature from discovery through testing. Here are the four PSDP items each artifact includes (whether or not you think you need it):
Task item = workflow process of artifact, there are implications on how to use this with a single developer and multi-developer team so ask for clarification.
Detailed Requirement item = what
Detailed Design item = how
Test Script item = verify either what, how, final implementation. Ask for clarification if you wish.
In PSDP Online, you've always had the ability to link items. However, each item is managed separately even when they have features in common. Take a look at the common things among the PSDP items managed by a PSDP Artifact:
Workflow - Only tasks have workflow, with a PSDP artifact, you get workflow with the artifact.
Actors - You can always link actors to a requirement item, design item, and test script. With a PSDP Artifact, the actors are managed at the Artifact level and are the same for all three.
Status - The status of the other items at the artifact level. When you change the artifact name or category, all four items are updated. When you link an actor to an artifact, the requirement item, design item, and test script are updated. The same is true when you change the project/app status.
The problem with collecting individual items is that the user inputting the item tends to put too much information in tasks and use requirement items and design items only as a secondary thought. When collecting project information, you generally collect a combination of what the customer wants (the requirement), how you want to code it (the design), how to test it (the test script), and even a bit of end-user documentation. Your tendency will be to put all of it in whatever bucket your looking at. A PSDP Artifact puts you on a single page where you can put information into their correct place, their correct bucket.
By using primarily Artifacts, you put yourself in the correct frame of mind while developing that feature from the first time you talk about it through testing it, and artifacts make managing linked items easier (one location to deal with name, category, linked actors, etc.)
PSDP Artifact Usage Strategy
The project team needs to decide on a PSDP artifact usage strategy. The project manager, analyst, or software architect can decide the usage strategy for the team but it is better if the whole project team is involved in deciding the strategy. There is no right or wrong strategy. More artifacts lead to a heavier process, less to a lighter. You can base your strategy on a free-form or consistent theme (or both). A free-form strategy doesn't really require any thought as members will be creating PSDP artifacts as they see fit. The problem with this approach is the ambiguity it introduces causes inconsistent usage, holes in documentation, and leads to an unwillingness to use them by team members. A consistent strategy makes more sense, leads to consistent documentation, and is frequently easier to implement because of the lack of ambiguity.
Applying Artifacts to a New Application A good rule of thumb is to create them based on intended deliverables or on the content of the requirements. For deliverables based, you can start with one PSDP Artifact per form and report and/or per table in the database skipping minor items. For websites you may want one per page. This deliverables based strategy works only if you're prototyping and creating the database at the same time that you are gathering requirements (PSDP recommends this approach).
If you are gathering requirements up front without defining the database nor prototyping, deciding on a usage strategy takes a bit more effort. Sometimes you can delay defining your strategy until you're well into the design phase. If you wish to start defining your PSDP artfacts during the requirements phase, you can base on them on the contents of the requirements. If you're using UML diagrams, you could create one PSDP Artifact per Use Case Diagram or per Use Case.
Applying Artifacts to an Existing Application You can apply PSDP Artifacts to an existing system that has ongoing development and/or maintenance. For desktop applications, start with one PSDP Artifact per form and report. For websites, start with one PSDP Artifact per page. If you have a utility that imports and/or exports data, start with one PSDP Artifact per import/outport combination. Perhaps add each artifact as you go forward in your development effort. If you touch it, make sure it has a PSDP Artifact.
Artifacts Can Document Client Expectations Another use for PSDP Artifacts could be to track and document what the client wants. Create one artifact per main requirement, expectation, and/or critical success factor. A nagging problem we always face is documenting what the client wants then design, build, and test it while maintaining a link back to the original requirement. PSDP Artifacts aid in your effort to make sure you fulfill each and every requirement. For doucmentation purposes, you can add as many additional requirement and design items as you wish. You can also add additional test scripts as needed.
Single Developer If you are a single developer, assign the artifact to that single developer and use it to track the completion of both the documentation of the artifact (requirement, design, and test script) as well as the building and testing of it. If you are part of a development team, assign the artifact to the resource gathering requirements and create additional tasks. If you want to track the building with a higher grainularity, add additional tasks.
Team Q. I've assigned the PSDP Artifact to one developer, how do I manage the filling in of design, the building of the artifact, and testing?
A. If one person is assigned to the filling in of the design items, create one or more additional tasks assigned to that person with a description to fill in all artifacts. If, for example, two developers are then going to build (code) the artifacts, assign one or more tasks to each developer with a description to build specific artifacts. For testing, you'll want a minimum of two tasks, one to complete the test scripts and one task to test each build (a test suite and results is associated with a build). The resulting defects have workflow with assignment built into each defect (a defect is really just a specific type of task).
PSDP Artifacts and Phases
Q. How do PSDP Phases relate to PSDP Artifacts and the usage of each?
A. They don't really. In PSDP Online, you set the PSDP Phase of tasks and their two sub-types defects and artifacts only. Requirement Items, Design Items, and Test Scripts do not use the concept of PSDP Phases because they are documentation-only items. You add various development tasks set to the appropriate phase to create, flesh out, and use them to build and test but they do not contain workflow themselves.
The PSDP Phase of Defects is always Phase 6 Testing & Rework. Although Tasks and PSDP Artifacts can be set to any PSDP Phase, their default is Phase 2 Requirements. For PSDP Artifacts, most of the time you will leave it set to it's default. On the other hand, you will set tasks to whatever phase the task belongs to.
Task, Artifact, and Defect Default Phases The default phase for a defect is Phase 6 Testing & Rework. The default phase for a task or PSDP Artifact is Phase 2 Requirements. Whether or not you have enabled PSDP Phases for a project, the defaults are always set just in case you enable PSDP Phases.
Even though PSDP Artifacts contain a Task, Requirement Item, Design Item, and a Test Script, it belongs to the requirements phase because the Requirement Item is the first real software documentation item. An additional task or tasks of filling in design items belong to Phase 4 Detail Design. The task of coding the artifacts belong to Phase 5 Initial Coding, and finally the task of completing of the test scripts and testing a particular build belongs to Phase 5 Testing & Rework.
Using Artifacts with PSDP Online
When working with an artifact, you can work on the artifact itself or drill into any of the four items for further details. In PSDP Online this is implemented in the following ways:
Add Artifact option - now there is an Add Artifact option on the tasks, detailed requirements, detailed design, and test scripts pages.
Artifact Button - now there is a Artifact button on each of the four edit pages that allow you to switch to the artifact view of the item you are editing.
New Add Artifact Option for Tasks, Requirement Items, Design Items, and Test Scripts
These list pages now have a new Add Artifact option:
Edit or Convert Items For existing tasks, requirement items, design items, and test scripts, you can convert them from the item list. For existing artifacts, the icon is colored, select it to edit the artifact.
While editing a PSDP Artifact, you can edit the main attributes of each of the PSDP Items, workflow, and project/application status. You can also link one or more of the actors that you've defined at the application level.
Abstract: The term software artifact has a general meaning in software development process. Several processes have used this term as part of their process. This article focuses on both the general definition and a specific implementation in PSDP Online.
What is a software artifact? Any nugget discovered and developed and used during software development and maintenance. Examples are requirement items, design items, diagrams, test script, and even code itself.
What is a PSDP artifact? In PSDP Online, a PSDP Artifact links together a task, requirement item, design item, and test script all with the same name and associated with the same project category (if used). You can edit a PSDP artifact as a whole or expand any of the four linked items to include more details.
A PSDP artifact simplifies some of the complexities of working with linked items. For example, you get workflow with the linked task, and actors and status of the other items at the artifact level. When you change the artifact name or category, all four items are updated. When you link an actor to an artifact, the requirement item, design item, and test script are updated. The same is true when you change the project/app status.
Prestwood Client Note - As a Prestwood client, it's a good idea to understand PSDP and PSDP Online. This article discusses how we use PSDP Artifacts to build better software for you and how they lead to the automatic generation of four PSDP documents throughout the process. If you have questions, please contact Mike Prestwood.
Developer Note - As a software developer, you should be familiar with software artifacts and how they're used within your process. Learning about PSDP Artifacts will help you decide how to do something similar in your process. If you're a Prestwood developer, you need to be familiar with PSDP Artifacts, how they are implemented in PSDP Online, and how they fit within your team's process.