Working collaboratively as team creating software-based products requires information flow. Not only need coding software developers to communicate the architecture and various quality aspects of the software artifacts to non-coding team members, but developers also need to know about things like business priorities, contract information, and market opportunities. This communication needs cannot be solely answered with a markup language and a source code management server. While this tool selection is a valid solution for developers or technical writers, it cannot be the whole story, especially for large teams. Software coding is only a small amount of the work to be done for a successful product. And I hate to admit - as a software developer loving to code - coding is not the most important one.
Communication is king. Creating documents nobody is interested in is a waste of resources. While only implemented features of a product are able to support users getting their work done, there is also the need to move information from one stakeholder's brain to another. Information is required to support stakeholders to make the right decisions. There is also the need to store information in a tool more reliable for recalling than the brain.
Information workers handle different kinds of information. But for software project we often work with the same set. Architecture decision, work instruction, contract, interface documentation, patterns, stakeholder description, codes, test plan, build plan, persona, user story, use case, meeting minutes, and so on and so on. Well, this set is quite large. Not every artifact is be a document in a wiki. It may be a bug report in a issue management system or an executable test case run on a continuous delivery server. In case a document is actual to be created to provide a given information, there is no need to reinvent the wheel for each document instance. Templates leverage the organization of the actual information. Team members should fetch the most appropriate template for the communication task at hand, add the information in a form their readers expect and push it to a location where interested parties can find it easily. This is about concentrating on the readers' demands and their expectations.
At smartics we work with Confluence as a team collaboration platform. Each member writes a journal which is readable by every member of the team. This is because records are easier to handle than documents since there is no need to update records. Albeit some information is better organized as documents than a flow of events organized by time and some tags. This is when Doctypes for V-Modell®XT, Doctypes for Service Management (ITSM, Information Technology Service Management) and other doctype add-ons enter the stage. If we need to compile information, we choose from the experience of other people to organize it. With space and page blueprints organizing information with projectdoc Toolbox in Confluence is quite easy.
While there are many ways to evaluate a delivery, we decided to use V-Modell®XT. This makes it easier to organize the work since the domain and its processes are well defined.
From the contract and specification we derived the scope of the delivery and specified the acceptance and test criteria for the delivery as a whole and its individual items. Running and documenting the tests has then been straight forward. In the end we used about ten different templates (e.g. delivery, delivery item, test specification, test protocol, and problem report) to evaluate the delivery.
Lessons learned
First we thought it natural to add protocols to their specifications. This way the whole thing, specification and protocols could be exported in one go. But it turned out that having protocols in their own tree would have been much simpler in our case. Since there had been a retest, we needed to document that one apart from the tests we conducted before. Therefore the blueprints now allow to organize test specifications and test protocols in two ways:
- Add test protocols to the test specification (our first approach)
- Add test protocols to the delivery description
We now also differentiate between a problem report and a change request. The problem report is a record derived from a test protocol. It makes it easier to list and reference the individual findings. A change request is a traceable ticket that may be the result of a problem report. There may be use cases where problem reports can be skipped. For instance, if it is only relevant to track the problem, but there is no need to have the original problem documented. In this case simply create a ticket, since the only important information is the current status of the problem solution process. If the problem report is passed to a team that organizes the tickets in their own issue management system, change requests may be created directly in that system. It is often waste to track a ticket in two different systems.
Documenting services from a management point of view made us delve deep into ITSM (IT Service Management).
Lessons learned
To distinguish between a system and a service has been the key takeaway. This separation allows to move the technical aspects away from the organizational and management view that focuses on the customer. Often technical information is better collected automatically from the actual systems (live data). In order to define and steer a service strategy, typically these technical aspects are often less relevant. There is a more abstract view on this information in form of service levels and qualities.
Another important point is the visualization of dependencies and information flows. Therefore we started to experiment with a Graph Extension that allows to transform a web of relationships between documents into a graph description to be rendered with a graph add-on (such as plantUML for Confluence).
In the end there is (still) often the need to export information from the wiki in form of static documents, mostly PDFs, to be sent to external stakeholders. Still this transformation takes quite a large amount of time (and we wished that everyone was working directly with Confluence), but we are working on it to get it done more quickly by increasing the amount of automation. Fortunately there is still room for improvement!
Doctype add-ons provide free space and page blueprints for the projectdoc Toolbox. Some of the latest doctype add-ons are currently only available on Bitbucket.
# | Name | Short Description |
|---|---|---|
| 1 | Core Doctypes | Provides a basic set of doctypes to create agile documentation. |
| 2 | Doctypes for Software Development | Provides doctypes to create documentation in software development projects. The focus is on documenting the architecture of the product, but it includes templates for other software development documentation requirements as well. |
| 3 | projectdoc Add-on for arc42 | Provides doctypes to document a system or software architecture based on the arc42 Template. |
| 4 | Doctypes for Agile Planning | Provides doctypes to collborate with your team. Run iterations and record discoveries that may be of interest at the end of the iteration or for even later reference. Quick notes are more easily added as records to the team's space than to the official documentation tree. Defer the talk to the documentation architect to the end of the iteration (if the discovery is still of interest). |
| 5 | projectdoc Developer Diaries | Provides doctypes to organize the developer's work by the employment of a diary. Take you personal planning and professional records to the next level! |
| 6 | projectdoc for Java Developers | A collection of blueprints for Confluence to create and work with documentation for Java projects. |
| 7 | projectdoc for Maven Developers | A collection of blueprints for Confluence to create and work with documentation for Maven projects. |
| 8 | Doctypes for Teamwork | Provides doctypes to define the checklists, processes, patterns, tools, and rules your team agrees upon. Writing them down makes them accessible for anyone - especially for new team members. Keep these documents short and to the point! |
| 9 | Doctypes for Business Strategy | Mission, vision, strategy for business planning and execution. |
| 10 | Doctypes for Service Management | Provides doctypes to document services and systems for IT service management (ITSM). |
| 11 | Doctypes for Project Management | Provides doctypes for documenting decisions, risks, open issues, and meeting minutes. |
| 12 | Doctypes for Risk Management | Provides doctypes for documenting and tracking risks. |
| 13 | Doctypes for App Manuals | Document macros, page blueprints, space blueprints, and components of your Confluence add-on. |
| 14 | Doctypes for V-Modell®XT | Use products (templates) from the V-Modell®XT in your Confluence wiki as blueprints! |
projectdoc Toolbox
If you want to learn more about the projectdoc Toolbox and how it helps to create good project documentation, please refer to the introduction video!
The following image is a link to a video on YouTube. When you click the link your browser will serve a page from youtube.com.
Very interesting, but way too fast?
Step through at your own pace with with our Prezi Presentation (external link to prezi.com )!
In the Online Manual you’ll find additional video material that introduces you in the concepts of the projectdoc Toolbox.
Refer to use cases and show cases for information on how to use the projectdoc Toolbox.