There should be a single page for each project, even if it becomes long, because the wiki will automatically maintain an outline of the sections in the page at the top of each page. Whereas many smaller pages require that such an index across pages be created manually.
The shared artifact should include the parts below, but they are usually created more-or-less sequentially, with each section providing information for the sections that follow:
- Essential requirements: these are a set of statements about what the finished project will accomplish, but not how.
- Functional specifications: an exhaustive exploration of features and details about what the project does, but not how.
- Software design: how it accomplishes what it does
- Implementation Details: data and process models, details about major components and their interactions
- SQA Plan: details about how the project can be tested
- Deployment Plan: the steps involved in deploying the project for general use
- Maintenance Plan: any steps required to keep the product or service operating after release
The shared artifact is the one place everyone knows to go to find details about the project.
The shared artifact is supposed to demystify the project. The beginning of it should be very easy for anyone to read. From the essential requirements even a layman should have no problem understanding the majority of what the project will accomplish. Certainly, anyone on the project team should have no problems whether they are in management or engineering.
As one reads down the page it gets more complicated until it reaches a point where primarily only software engineer might understand or even be interested. This is what success looks like for a document with many different audiences: people can easily find the parts that interest them, and the project is describe in increasing levels of detail so that people who only want an overview find the document as easy to use as those who require an in-depth discussion.
Having more than one target audience for document can sometimes doom a writing effort to failure for one or more of the audiences. The shared artifact bucks this trend by compartmentalizing information by how it is used and releasing the Krakken of complexity by degrees only as the document proceeds, so less-technical readers can are not discouraged when they try to use it, especially the first time.
The shared artifact grows through the lifecycle of the project. As the project is developed engineers should revise the shared artifact so that it remains in sync with what is actually done in the project. When the project is done, the shared artifact serves many purposes:
- Provides a way to train new team members.
- Provides the starting point documentation for the next phase of the project
- Provides visibility into the productivity of the software design process
- Shifts risks earlier in the engineering process, which increases profitability by reducing losses
- Causes important questions or issues to be raised sooner with stakeholders
- Minimizes assumptions by all parties
- Reduces changes of misunderstandings and rework
- Improves the accuracy of bids
- Document the project through the entire software development lifecycle
- Provides transparency to understand how the project definition has changed over time, and who changed it (e.g. feature creep, scope creep, unspoken assumptions)
- Ensures that everyone is using the latest version of the project documentation
- Allows peer review of the software design to increase quality, reliability, testability, performance, scalability and resource efficiency, etc.
- Allows management review of a project before implementation begins