Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Content Layer
id1190165082
Content Column
width100%
id1190165083
Content Block
id1190165084
Document Properties Marker
doctypeproject
hidetrue
overridetrue
Doctypeprojecthide
Nameprojectdoc Demonstration Space
Short DescriptionThe demonstration space of projectdoc features. Create this space in your Confluence instance using a space blueprint 'projectdoc Demonstration Space'.
Tags
Tag List
namesDemospace

Sort Keyhide
documentation-json-urihttps://www.smartics.eu/confluence/download/attachments/12156954/docmap.json?api=v2hide

Welcome to projectdoc!

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

Note Box

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

Alternative ways of starting with properties

Tour
render-as-definition-listtrue
replace-title-with-nametrue


Widget Connector
urlhttps://www.youtube.com/watch?v=9uI1FBUR4i8

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!

Panel
borderColordarkgreen
bgColorlightgreen
titleColorwhite
borderWidth3
titleBGColordarkgreen
borderStylesolid
titleWhat 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.

Panel
titleTable of Contents

Table of Contents
maxLevel3
minLevel2
outlinetrue
indent10px
excludeResources
stylenone

Info Box

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.

Panel
borderColororange
borderWidth3

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.

Widget Connector
urlhttps://www.youtube.com/watch?v=_hQEo-r8Rq8

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

Info Box

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


Section
level2
titleTemplates

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.

Section
level3
titleTemplates, 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.

Tip Box

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

Section
level3
titleFree 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!

Tip Box

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.

Caution Box

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

Panel
bgColorwhite
titleColorwhite
titleBGColororange
titleInstall Templates!

Install now via

Atlassian Marketplace

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


Section
level2
titleBasic Features Show

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

Section
level3
titleSelecting 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.

Panel
bgColorlightyellow
titleBGColorwhite
titleDisplay Table Examples
Section
level4
titleTable Example

This example shows the selected pages in classic tabular form.

Panel
bgColorwhite

Display Table
doctypedoctype-addon

Section
level4
titleSame 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:

Panel
bgColorwhite
Display Table
doctypedoctype-addon
render-modedefinition
Section
level4
titleSame 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.

Panel
bgColorwhite
Display Table
doctypedoctype-addon
render-mode5+
selectName, Description, Requirements, Homepage, Install via
header-translationsInstall via=Available on
Section
level3
titleSelecting 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".

Panel
bgColorlightyellow
titleBGColorwhite
titleDisplay Property Example

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

Display Property
documentCore Doctypes Demo Page
property-nameHomepage

Section
level3
titleTransclusion

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

Panel
bgColorlightyellow
titleBGColorwhite
titleTransclusion Example
Transclusion
documentCore Doctypes Demo Page
idsDescription

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

Tip Box

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

Hide From Reader

Note that you only see a reference box around the transcluded content, if you are not a reader. As an author this helps you to jump to the original source quickly!

Tip Box

Please also note that you have access to this tip only, because you are in the role of an author. This paragraph is hidden from users with only read access.

Section
level3
titleSections

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.

Panel
bgColorlightyellow
titleBGColorwhite
titleTransclusion 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.

Display List
doctypedoctype-addon

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

Content Marker
hidetrue

Cheese

Panel
borderColordarkred
bgColorlightyellow
titleColorwhite
borderWidth3
titleBGColordarkred
titleTrouble 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.


Info Box

There are many more macros provided by projectdoc!

Info Box

There are many features provided by projectdoc!