- Created by Robert Reiner, last modified on 17. Jun 2016
projectdoc Toolbox
Software documentation is a large field to communicate with different stakeholders with different information needs. This topic introduces to the basics of documenting a project with a wiki.
When you launch a project and you want run your documentation with a wiki, your scope is already narrowed. But it is not that narrow, that you do not have to decide some key points.
Document or Record?
The first question to answer is this:
Is this space for team collaboration or do you want to publish this space to be read by other stakeholders?
One important trick is to not merge documents with records. Information stored in documents has to be updated. Records do not. The team's collaboration work is largely a collection of records. Some of them may evolve into documents at which point they have to move to a document space. So use separate spaces for documents and records.
If you are looking for tools that support your team's or your personal records, there are two projectdoc doctype add-ons to support you:
| Add-on | Short Description |
|---|---|
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). | |
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! |
One Reader or an Audience?
The second question is this:
Do your stakeholders share the same view on your project?
Probably not. A software project often requires documentation for the following information:
- Developer Handbook
- Where can I find which information system?
- What project rules have to be applied?
- ...
- Operations Handbook
- How to install the product?
- How to monitor the product?
- ...
- User Manual
- How to work with the product?
- ...
- Test Concept
- Which tools do we use?
- How do we test?
- ...
- Software Architecture Documentation
- What is the structure of the product?
- Why have which decisions been made?
- ...
- ...
Each document has a different set of stakeholders as audience. It would be quiet confusing for a user to be confronted with the documentation of the software architecture or the software architect to pick architectural information from an installation guide.
Since these documents share information, like information on roles or stakeholders, it makes sense to define them in modules. This allows to work collaboratively as a team on the documentation and assemble these document fragments in documents like handbooks, manuals, and concepts.
The Tour doctype is defined to provide alternative views on topics that are assembled for a target audience.
Generated or Written?
And finally you may ask:
How can I keep my documentation up-to-date?
Not all information has its origin in the wiki. Some information is derived from test cases, requirement tools, artifact repositories, or the source code itself. The closer a documentation is to the code the more likely it is for it to be up-to-date. Therefore many developers prefer to check in the documentation with the source code. But there are two drawbacks from this approach:
- The release cycle of the product and its documentation are aligned so that both have to be released at the same time. But the product may work perfectly, while the documentation does not. In this case you just want to change parts of the documentation, but do not need to make a release for the project. Or the product needs a bugfix that does not take effect on the documentation. Then you want to release the product without building the documentation. You may separate product and documentation into separate projects to fix this, but this will move you code away from your documentation.
- Not everybody on the team who works on documentation knows how to use a source code management system (SCM). And if she does, she may not be trained to work with a plain text format.
To tackle the up-to-date problem projectdoc provides macros to to transclude parts of documents from remote information systems. This way the information may be fetched from a SCM and rendered in the wiki. This keeps the information presented in the wiki up-to-date and accessible.
The following macros allow to transclude or link information on remote information systems:
- Enterprise Architect Image Link Macro
- Renders an image generated from an Enterprise Architect diagram, transcluded from a server.
- HTML Snippet Macro
- Transclude HTML content from a remote server.
- Hudson Link Macro
- Render links to jobs and services on a Hudson server.
- Javadoc Link Macro
- Links API documentation pages for Java elements.
- Nexus Link Macro
- Renders a link to an artifact stored on a Nexus server.
- Site Link Macro
- Links to a resource on a versioned site.
- Sonar Link Macro
- Renders a link to a project on a Sonar service.
- Subversion Link Macro
- Renders a link to a resource on a Subversion (SVN) repository.
- Subversion Transclusion Macro
- Transcludes a snippet from a project on a Subversion (SVN) server.
- System Image Link Macro
- Renders an image transcluded from a remote server.
- System Link Macro
- Links to a resource on a server.
- System Transclusion Macro
- Transclude content from a resource from a remote system.
- Text Snippet Macro
- Transclude text content from a remote server.
Resources
More resources on how to work on documentation spaces with the projectdoc Toolbox.
- Software Project Documentation
- How to start your software project documentation? Here are the steps to get started with Confluence and the projectdoc Toolbox.
- Create a Diary in a Personal Space
- The recommended way of creating a diary with the Developer's Diary Add-on is to add a page with the Diary Template in one's Personal Space.
- Use Cases
- An overview over the use cases for which the projectdoc Toolbox provides support.
- Hands-on Tutorial
- Get started with the projectdoc Toolbox: learning by doing
- Tips
- List of tips to use Confluence with the projectdoc Toolbox and fun! Tips address users of different experience levels.
