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!
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.
Macros and Conventions
projectdoc provides macros that allow you to
- 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 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.
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.
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.
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".
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.
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.
Sections make it also easier to move them around a document per drag-and-drop.
There are many more macros provided by projectdoc!