Questions and Answers

I'm evaluating projectdoc for use with my team. Where can I get more information on projectdoc and the doctype add-ons?

We provide detailed information about the limitations users may face when using projectdoc in our Evaluation Topics article.

The documentation for version 1.x is found at projectdoc Toolbox.

My team and me are in a problem. We experience difficulties with out documentation. We do not know where to add new documents and cannot find information of interest in this big ball of wiki pages (or spaces). We know we have a problem, but cannot see what it is, let alone how to solve it! Can projectdoc help us?

There is no easy solution for a complex problem, if the problem is not yet understood.

Users often have difficulties to organize their information collaboratively. Often nobody feels responsible to define a documentation concept that meets the requirements for the stakeholders (users, team members, management, ...). A wiki gives the promise that collaborative work will eventually result in a proper organization. But it is hard work and you have to discover the most suitable structure with your team.

projectdoc provides macros to help you define the templates for the documents you require. It further supports you to organize your document instances in your wiki space and make the space navigable. Have a look at Installed it! But my documentation did not get any better at the instance of installing! for hints on how you may start to use projectdoc for your documentation. But it all starts with an analysis of your stakeholder's requirements, your roles, and your content ...

If you are looking for advice on defining your information organisation, have a look at resources concerned with Information Architecture. Depending on your work there may already exists standards or quasi-standards to follow.

projectdoc supports you to employ the selected standard in a Confluence wiki. We also provide free doctype add-ons that may get you started to define your own set of page and space blueprints.

Have a look at Document Types and Templates to learn about doctypes, blueprints, and templates.

For an introduction to existing free doctypes jump to Doctypes Introduction or to Doctypes for alphabetical listings.

Documentation serves a specific purpose. Therefore projectdoc provides macros to help you to define the templates for your documents more easily.

There are documents that are crucial for the success of your project and there are those that don't. There is no need to invest much time in the latter, but unfortunately they have to be there. Examples of these doctypes are:

• Role
• Resource
• Tag
• Category

You may use the Core Doctypes to get you started and preserve time you can invest in defining the project's most important document types.

I've installed the Software Developer Doctypes. How am I supposed to use them?

The doctypes provided by the Software Development Doctypes are used to document artifacts of an agile software development project. Agile implies that you do not want to follow a process to create documentation, but that you and your stakeholders define the type of documents that are useful for the project and the users of the products you create.

We do not assume that this set of templates defines completely what you need. This would probably defy the notion of agile as we have defined it above. Instead look at these doctypes as a starting point for the definition of your templates. Select those that generate value for you and deactivate those that do not.

Tour for Template Authors may help you to get started with defining your own templates.

I am unsure of what the doctypes provided by the Agile Planning Add-on are used for. How are these templates useful?

Documents have different properties. One property is its requirement to be updated. While the handbook for an artifact probably needs to be updated on each new release, the notes in a developer diary does not call for maintenance. It is often important to separate those versioned documents from the inversioned records.

The Doctypes for Agile Planning help you to create space for records and the collaborative work of a team during an iteration. The add-on provides a space blueprint to create spaces to work in collaboration. Create Iterations to store all information that is relevant for a particular sprint. During and especially at the end of the sprint decide, which information should be moved to a more prominent space (especially to a place where it further needs to be maintained) and which information could be stored in the iteration without requiring any update. The information of the iteration may still be available, but due to its diary style of usage, demands not to be up-to-date.

There are also templates to prepare your Review or Retrospective. You'll also find a template for User Stories (in case you want to add more information with the tools of a wiki instead of your issue management system) and Improvements (to keep track of you ongoing improvement process).

These templates are just suggests to get you started. You probably want to adjust them to meet your specific documentation requirements.

I have installed the Developer Diaries Add-on. How am I supposed to use them?

Similar to the Doctypes for Agile Planning the Developer Diaries Doctypes help to store information you gather during your work on a project. You do not want to burden yourself with updating these information. Rather you want to log the information to your journal to gain insights and have a reference for later use.

While the Doctypes for Agile Planning target at helping a team to collaboratively work within iterations and record information relevant to them, the Developer Diaries help individual developers to track their work and improvement.

Organize the events of a day in your diary. Keep everything on a separate wiki page to make this information easy to reference and find. Group information into clusters of Subjects, Tags, and Categories. Track your excitement and mood of your working days.

Developer diaries help you to organize your discoveries easily.

I have installed projectdoc on my Confluence server.

What am I supposed to to do to get started?

The following steps may help you get started:

1. Get familiar with projectdoc: projectdoc Introduction
2. Get your hands on:
   1. Read the Hands-on Tutorial
   2. Or explore on your own:
      1. First create the demonstration space to get started with projectdoc on your server
         or explore the demonstration space as a reader on projectdoc Demonstration Space
      2. Then you may start with a blank space and experiment with macros using the simple Blank Document Template.
      3. Explore some templates
3. You may also check out the Getting Started FAQs

I have created a space, but I am unsure of what I am supposed to do next!

Users often have not enough privileges to create their own spaces within the wiki. This is very unfortunate. So we cover first the use case, where a projectdoc space is available and then we give some tips on how to deal with a standard space.

I have installed projectdoc, but I am unsure about how my existing wiki spaces can be improved with projectdoc. What should I do next?

projectdoc provides macros to enhance the navigability and findability of a space. The price to pay is to define documents with properties (to select documents) and sections (to transclude content).

To transform an existing space check if you can

• Employ single sourcing: Identify large pages serving multiple purposes and make them modular
• Describe your content: Add the Document Properties Marker Macro to your pages to add descriptive information and metadata
• Link your content: Use the Display Table Macro, Tour Macro and Display Document Property Macro to add navigation links to your pages
• Search in your space: Use the descriptive properties of the documents

Unfortunately this is a manual process that will enhance the navigability and findability issues only step by step.

I have installed projectdoc, but my existing documentation did not get any better! How long do I have to wait? Do I really have to use projectdoc templates and projectdoc macros by myself?

projectdoc is indeed no silver bullet to shoot at any wiki space and expect that a less-than-optimal documentation will magically turn into something more useful. projectdoc simply provides macros to define templates that make it easier to build sound and easy-to-use documentation. So a team deciding to employ projectdoc have to follow some conventions:

1. Define projectdoc documents by using
   
   1. Document Properties Marker Macro to define document properties
   2. Section Macro to define sections
2. Use projectdoc properties to describe your content
3. Use projectdoc to enhance navigability
   1. Provide Short Descriptions for your documents
   2. Use the Display Table Macro to automatically create lists of references upon query constraints
   3. Use the Tour Macro to define lists of references, transcluding information from the referenced documents
4. Employ modular documentation
   1. Define documents for information bits by using the Module Doctype
   2. Transclude content with the Transclusion Macro and the Transclude Documents Macro
   3. Transclude document properties with the Display Document Property Macro or one of its siblings
5. Use projectdoc to communicate the current development state of your documentation
   1. Define the current state using the Iteration Macro (this is included as the Iteration Property in most doctypes)
   2. Use box macros like Pending Box Macro or Feedback Box Macro to communicate with your team mates

It is recommended to make yourself familiar with projectdoc. Start with Installed it! What now? and check the resources of this web site.

I'm overwhelmed by the number of macros provided by projectdoc! Which of the macros are most useful to me?

Unfortunately there is no quick answer on which macros are most useful in any context.

If you are a beginner, we recommend to get familiar with the following macros first:

The overview lists all projectdoc macros in alphabetical order. You may experience the Macros Introduction as a more gentle approach, since the macros are introduced in a semantic context.

I'm overwhelmed by the number of templates provided by the free add-ons! Which of the templates are most useful to me?

The selection of templates depends on what you want to document. Usually you have to design your own set of templates that meet your requirements exactly.

For templates that do not belong to your core domain, your requirements may be less demanding. You may also want to check existing templates for ideas and then invent your own (or adjust the ones that have been installed). In these cases have a look at Doctypes for a list of templates we provide for free.

We provide tours for roles that introduce the central templates of the Core Doctypes Add-on:

There should be more than 20 page blueprints in the core add-on, but I find actually none (besides the Blank Document template that is only useful to get started).

Where are the blueprints?

The original projectdoc core add-on has been divided into the core add-on that contains the projectdoc macros and the core add-on that contains the templates.

To provide two add-ons where there was once just one, makes it easier for teams to define their own templates with having to deactivating our core templates. It makes it also easier for us to deliver them, since the two projects have different release cycles.

The drawback is that users that want to employ the core templates have to install them separately.

The add-on containing the blueprints is free of charge (only the add-on containing the macros is commercial). We plan to release its source to make it even easier for users to use them as a basis to define their own templates.

I need more support to organize my documents in my Confluence space(s)! How can projectdoc help me?

There are basically three levels at which projectdoc helps you to organize information:

• Document Level: templates define the properties and sections of a document and their ordering
• Space Level: space templates define a basic layout using index and homepages
• Wiki Level: search and delegate spaces extend your organizational structure over several spaces

Wiki Level

With delegate and search spaces you can link clusters of spaces together.

• Delegate spaces provided documents to be applied to multiple spaces - e.g. roles or qualities are use. 
• Search spaces are consulted by all query macros (such as Display Table Macro) to fetch documents marching their constraints.

Cool Use of Homepages

 

If you remove a homepage for a doctype from a space, sending a document to its homepage will search in the delegate spaces for the homepage for the document and store it there automatically.

If you later decide to recreate the homepage for a type, use the homepage wizard. Every doctype add-on provides one wizard to create any homepage that add-on supports.

For instance the Core Doctypes Homepage wizard helps you to create homepages for the following doctypes:

On The projectdoc Toolbox for Atlassian Confluence we list a couple of resources that may help you to define your problem in more detail:

The conceptual FAQs may also provide some guidance.

On The projectdoc Toolbox for Atlassian Confluence we list a couple of resources that may help you to define your problem in more detail.

The conceptual FAQs or "Think big, start small" may also provide some guidance.

And finally if you still encounter any difficulties in using projectdoc or in how to get started, please send us a support email!

Moreover we would love to

arrange a free meeting / arrange a free 1 on 1

for you!

I need better navigation in my Confluence space(s)! How can projectdoc help me?

To enhance the navigability of your space, use labels, add automatic lists or tours.

I need better way of finding information in my Confluence space(s)! How can projectdoc help me?

If you want to enhance your ability to find information in your wiki, one way is to add metadata to your documents. projectdoc provides the Document Properties Marker Macro to add properties to your documents.

These properties will be added to the Lucene index and are therefore available not only to macros conducting searches (like the Display Table Macro), but also to run queries via search boxes.

Please note that only properties and not sections are added to the Lucene index.

projectdoc provides some enhancements for queries that are only available in projectdoc macros. Please refer to Search Tips for details.

We have problems keeping the information in our Confluence space(s) up-to-date! How can projectdoc help me?

Modular documentation is easier to work on collaboratively and supports single sourcing. Single sourcing implies that an information is provided in one place and only one place. If the need arises to update a piece of information, e.g. due to a new release, the information is only updated in one place. This is much easier than updating an information in multiple places.

projectdoc supports modular documentation and single sourcing. First there is a doctype for documentation modules. Provide the information in a module and reference or transclude it from all other documents. While you may add information to any document and reuse this from there, the module doctype provides a query that automatically lists all documents that transclude the content (references to the document are already built into Confluence on the Page Information).

Here is an example of a module document:

The "Content" section can be transcluded by the Transclusion Macro. The section titled with "Transcluded By" lists all documents that import this text fragment.

I need more support to organize team work in our Confluence space(s)! How can projectdoc help me?

I have a question, a feature request, or feedback about projectdoc (or an other product of smartics). How can I get in contact with the support team?

Just send a support request per e-mail (support@projectdoc.smartics.de) → Get Support (e-mail)

Moreover there are a couple of options to get in touch.

Please contact your Confluence administrators and ask them, to provide you with a support zip file.

For more information on how to create this zip file, please follow the instructions provided by Atlassian: Creating a support zip file.

Please send to support@smartics.de an E-Mail with this zip file as attachment.

I am using projectdoc and need to find an answer to a specific question to complete my task. Where can I find answers to my question?

There are a number of locations to find answers to your questions concerning projectdoc:

1. You may ask questions, provide feedback, or request a feature feature
   1. publicly on Atlassian Answers
   2. privately by creating a ticket
2. You may also browse known issues on the JIRA server.
3. You my find your answer on the projectdoc wiki or the space that is dedicated to version 1.x for Confluence.
4. Finally you may find your answer on the list of frequently asked questions, particularly on the following list concerned with questions on working with projectdoc.

Some of the values in the property table are not transcluded to other documents. I expect certain hits in the display table, but they are never showing up!

Where is the problem?

Problem

Some macros are quite picky about recognizing values in the property table. Property values have to be unformatted. That is they should usually not contain any formatting information. Most macros allow unordered lists or links, but are usually distracted by paragraphs or other (nested) HTML element constructs.

The problem is in matching properties that contain additional markup that often has been added unintentionally. Problems often arise, if content is copied from another website to a property value. The copying adds additional markup that is not rendered, but makes proper resolving of the values impossible.

Solution

• If you want to solve those problem, please install the Confluence Source Editor. It not only helps to make the markup visible, it also allows you to remove it.
• In case you cannot install the Confluence Source Editor, we suggest to remove the table line and retype it. You can of course reuse any macros. But be careful with copying texts, since you are in danger for copying the invisible HTML elements you intend to remove.

I want to define a query for my documents, but I cannot get the syntax of the where clause right! Where can I find documentation?

Please refer to the Search Tips.

The Display All Document Properties Macro provides access to the properties and artificial properties a document provides in tabular form.