- Created by Robert Reiner, last modified on 10. Aug 2018
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.
Alternative ways of starting with properties
- Hands-on Tutorial
- Get started with the projectdoc Toolbox: learning by doing
- Learning projectdoc
- Getting started with the projectdoc Toolbox is not easy. Some basic concepts are more than just good-to-know and the number of macros and doctypes may be simply overwhelming. This tip gives some advice on how to get started.
- Tips
- List of tips to use Confluence with the projectdoc Toolbox and fun! Tips address users of different experience levels.
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!
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.
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:
- Homepage of projectdoc - provides version independent information
- Homepage of the projectdoc V1 - information related to the version of projectdoc you are using.
- projectdoc Introduction Video - with some explaining text.
- Getting Started - a list of further information to get you started.
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.
- Create the projectdoc Blank Space
- Add a new document based on the Blank Document Doctype
- Add some document properties to the properties table on top of the document
- Add some new sections to the document
- See the Display Table Macro (see Automatic Lists) at work: experiment by selecting documents by their properties
- 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 now via
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.
Table Example
This example shows the selected pages in classic tabular form.
| Name | Short Description |
|---|---|
| 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 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.
Error rendering macro 'projectdoc-display-table'
person must not be null
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".
For transcluding document properties there are a couple of macros, but the most basic is Display Document Property:
Transclusion
You may also employ single sourcing via the Transclusion Macro. This macro allows to transclude any section defined with the Section Macro.
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:
- Organize Information
- Identify People
- Modularize Content
- Categorize Content
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.
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.
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:
- Use the Confluence Source Editor and check what is really in there (recommended)
- Create a new table row and type in the content manually. Then erase the buggy row.
There are many more macros provided by projectdoc!
There are many features provided by projectdoc!
