Page tree

 

Welcome to projectdoc!

This is a starting space to show some of the projectdoc features.

 

This space can be created by users of the projectdoc Toolbox by using the projectdoc Demonstration Space Blueprint.


Or step through at your own pace using the presentation with Prezi !

See projectdoc Introduction for more information on all the fancy topics in the video!

What Problem does projectdoc solve?

The Problem

Wikis are a great way to add documents relevant for a software development project. After a splendid couple of weeks the highly motivated team added plenty of information to this space. But step by step the information is often difficult to find, because wikis impose very little structure on the documentation architecture. New information is difficult to add, since no one keeps track on the overall goal of the documentation endeavour.

The Solution

projectdoc tackles these issues by adding structure to the organisation of documents and structure to the individual document types. The team can still benefit from the lightweight approach by using a wiki (instead of a specialized tool or content management system), and combine them with structures the team agrees upon.

projectdoc supports agile teams in writing project documentation collaboratively. It is particularly useful for projects where everyone on the team is (potentially) involved in creating documentation.

Table of Contents

 

You may use this as a base for your real spaces, too.

Instead we recommend to install free doctype add-ons that meet your documentation requirements better and start by creating spaces with the blueprints provided by these add-ons.

Resources

In case you are looking for information on how to use projectdoc, we recommend the following resources on the internet:


Macros and Conventions

projectdoc provides macros that allow you to

  • write,
  • extend,
  • reuse,
  • navigate,
  • search,
  • and read

your documentation in Confluence more easily! There are also some conventions that are useful to learn. The macros and conventions support template authors to define templates for your team and support authors to contribute information in the collaborative work on creating documentation.

Or step through at your own pace with with our Prezi Presentation!

 

projectdoc is about macros, conventions, page templates and space templates.


Templates

Templates help you to create similar structured documentation that is easy to read and to extend. They are the backbone to help you creating your documentation collaboratively, albeit having a conform structure.

Note that templates do not help you on wording! If you have high quality demands, you'll have to add some additional rules to your documentation strategy. For every language there should be some guidelines to reference. Your technical writer will probably assist you in this task.

Templates, Blueprints, Doctypes

We refer to templates since this term is most commonly known. The implementation of templates in Confluence is called blueprints. Technically a blueprint may contain multiple templates, but in case of projectdoc there is usually a one-to-one mapping. We use the term doctype if we want to reference the logical model of a document, which is basically a list of document properties and sections. Doctypes are blueprints that require projectdoc macros.

 

If you are new and just want to get started, you may safely think of templates whenever you read blueprint or doctype.

Free Templates

It is important to note that the core add-on does not come with any production-ready template! Therefore we strongly recommend that you check out the free doctype add-ons to see which one will get you started more quickly!

 

Actually there is one very simply template called the Blank Document Doctype. Together with the projectdoc Blank Space you may start to get familiar with projectdoc.

  1. Create the projectdoc Blank Space
  2. Add a new document based on the Blank Document Doctype
  3. Add some document properties to the properties table on top of the document
  4. Add some new sections to the document
  5. See the Display Table Macro (see Automatic Lists) at work: experiment by selecting documents by their properties
  6. Continue with the examples on this page

Why are no templates included? We think that agile documentation is all about using only the kind of documentation that is relevant for your project and your team. Therefore the team should select the templates they want to employ be themselves and better start small than be overwhelmed by large quantities of new templates.

 

In almost all uses cases you want to install the free Core Doctypes Add-on for projectdoc!

Install Templates!

Install now via

Atlassian Marketplace

We strongly recommend to install it now, if you have not already done so.


Basic Features Show

Here we introduce you to some of the features of projectdoc.

Selecting Documents with Automatic Lists

The space has been created with three documents of type "doctype-addon". Usually you would create a template for them, but we added them manually to show you how to select on documents you provide.

The following tables are examples using the Display Table Macro. It allows to select on projectdoc documents based on document properties. The document properties are stored in the table on top of each projectdoc page. A projectdoc pages is essentially a Confluence page the uses the Document Properties Marker Macro constraining the properties table and the Section Macro for defining the sections.

Please note that this example is somewhat artificial: usually a template author would define a doctype for the "doctype-addon" type and define the properties and sections that are part of it.

Display Table Examples

Table Example

This example shows the selected pages in classic tabular form.

Name Short Description
A free add-on to provide the most basic blueprints for projectdoc.
A free add-on to provide blueprints to document your software project with projectdoc.
A free add-on to provide blueprints to help your agile team work collaboratively using projectdoc.

Same Table rendered as Definition List

Since the result of the previous example contains only two columns, it may be rendered easily as a definition list. Here it is:

projectdoc Core Doctypes
A free add-on to provide the most basic blueprints for projectdoc.
projectdoc Doctypes for Software Development
A free add-on to provide blueprints to document your software project with projectdoc.
projectdoc Doctypes for Agile Planning
A free add-on to provide blueprints to help your agile team work collaboratively using projectdoc.

Same Table rendering Sections and Properties

You are not restricted on selecting properties. Information from sections may also be included. In this example we also change the representation, since the amount of information in the sections is quite large and will be hard to read in its classic tabular form.

Note that we also replaced the property name "Install via" with "Available on", just to show you that you may change the column headers easily.

projectdoc Core Doctypes
Name
Description

This free add-on provides blueprints for the projectdoc. Make it easy for you and your agile team to collaboratively create documentation in your wiki.

The add-on uses projectdoc macros to define core page & space templates. This helps you to create project libraries of resources, define glossaries and create address books. Install them to get you started with projectdoc quickly!

The following doctypes provide page blueprints:

We do not expect to meet all your requirements. Use it as a template to create your own! Be agile!

Requirements

This free add-on requires the commercial projectdoc add-on. You cannot use it without a licensed version of projectdoc installed on your Confluence server!

Homepage
Available on
projectdoc Doctypes for Software Development
Name
Description

This free add-on provides blueprints for the projectdoc. Makes it easy for you and your agile team to collaboratively create software architecture documentation in your wiki.

This add-on provides software development blueprints for the following doctypes :

We do not expect to meet all requirements. So feel free to use this set of blueprints as a template to create your own! Be agile!

Requirements

This free add-on requires the commercial projectdoc add-on and and the free Core Doctypes. You cannot use this add-on without a licensed version of projectdoc installed on your Confluence server!

Homepage
Available on
projectdoc Doctypes for Agile Planning
Name
Description

Provides blueprints for agile planning, including the following document types:

At the heart of this set is the iteration blueprint. We suggest that each agile team creates a page for each iteration to log all information that looks interesting. The team may then decide at the end of the iteration, which information goes to the global documentation, which should be archived or permanently discarded.

The iteration page is therefore a kind of diary, allowing to add information collaboratively. But there is no burden on maintaining the information on this page and its subpages.

We do not expect to meet all your requirements for your documentation. So please feel free to use this set of blueprints as a template to create your own!

Requirements

Please note that you require the commerical projectdoc Add-on and the free Core Doctypes Add-on and Doctypes for Software Development to run this extension.

Homepage
Available on

Selecting Document Properties

Single sourcing is to have a single place where you store one information. If you want to show this information in another place you do this via transclusion. Transclusion is the technical term for "fetching the information just-in-time and displaying it in another context".

Display Property Example

For transcluding document properties there are a couple of macros, but the most basic is Display Document Property:

projectdoc Core Doctypes Homepage

Transclusion

You may also employ single sourcing via the Transclusion Macro. This macro allows to transclude any section defined with the Section Macro.

Transclusion Example

This free add-on provides blueprints for the projectdoc. Make it easy for you and your agile team to collaboratively create documentation in your wiki.

The add-on uses projectdoc macros to define core page & space templates. This helps you to create project libraries of resources, define glossaries and create address books. Install them to get you started with projectdoc quickly!

The following doctypes provide page blueprints:

We do not expect to meet all your requirements. Use it as a template to create your own! Be agile!

Use transclusion to define content at one place and use with a number of documents.

 

The requirement sections of the sample "doctype-addon" documents would naturally call for such a treatment.

Sections

You have already seen on feature of the Section Macro: its content may be transcluded. The other important feature is, that you do not see the section, if the body of the section is empty! This makes it a valuable tool for template authors. A template may define the order of sections, but if there is no content, the reader's view is not cluttered with non-information.

Transclusion Example

Have a look at any of the following documents. Each has a section called "FAQ", but since no content is provided, the section is not rendered in view mode. Switch to the edit mode and find the FAQ section at the end of each document.

Sections make it also easier to move them around a document per drag-and-drop.

Trouble Shooting!

Queries show no Results!

On page generation the pages are added to the Lucene Index. This index allows documents to be found.

If your query is supposed to find documents recently added, try to reload the page. It depends on the overall performance of your system how long the indexing process takes. The speed of indexing is not in scope of projectdoc and is managed by your system administrator.

My Queries are Lacking Results!

Selection of property names and values is very strict. If you happen to add some fance HTML fragment instead of a simple value, the result may never match.

Problems usually arise if you copy paste values for document properties.

Two options here:

  1. Use the Confluence Source Editor and check what is really in there (recommended)
  2. Create a new table row and type in the content manually. Then erase the buggy row.