Support Recalling

...

Document Properties Marker

override	false

Short Description

Links allow readers to find related information. Autocomplete allows authors to recall the names of related information. Let's have a closer look on the Autocomplete Feature of the projectdoc Toolbox!

Doctype

topic

hide

Name

Support Recalling

Short Name

Parent

Parent Property

property-name	Name

hide

Audience

Name List

doctype	role

render-no-hits-as-blank	true
names	Author, Documentation Architect, Template Author
property	Audience

Subject

Name List

doctype	subject
property	Subject

Sponsors

Name List

doctype	stakeholder
render-no-hits-as-blank	true
property	Sponsors

Sort Key

hide

projectdoc.autocomplete.activeConstraint

$<Iteration>~(Released, Production, Deprecated) OR $<Doctype>~(event,todo)

hide

projectdoc-section

show-title	false
title	Description

Our brains are not that good with recalling information. Even paper is better¹. That is why we write documentation even if the documented tool is only used by us or a small team²: we communicate with our future self, relieve our overworked brains from the necessity to recall information. The projectdoc Toolbox for Confluence now brings this principle of "brain relieving" to authors, especially when they try to recall the name or title of a document. This new feature is called Autocomplete and this tip provides some insights for authors, but also for information architects or template authors, on how to use this brand new supplement of the projectdoc Toolbox.

Section

title	Summary

Section

title	Prerequisites

Section

title	Autocomplete Parameter Values

The Autocomplete Feature currently supports authors to edit values of macro parameters. Macros are used for rendering, referencing, compiling, and transclusion, or multiple purposes. Macros of the projectdoc Toolbox that deal with referencing do this by identifying a document either by space and page title or by doctype and name. To select the title or name, the Autocomplete Feature provides support.

Image Added

The Autocomplete Feature also allows to select doctypes for macro parameters and – currently for only one macro – the property names.

Section

title	Constraints

The Name List Macros and the Display Document Property Macros allow template authors to specify constraints. This reduces the result set which allows authors to select a value from.

The constraints can be defined by macro parameters or by a space property.

Section

title	Name List in Action

The Name List Macros require a doctype to be set. Without a doctype these macros will not offer any names for selection.

Once a doctype is selected, no character is required to be entered to present a list of valid values. If the parameter field has the focus, simply press the down key or hit space to show the valid values in a selection box.

Image Added

In addition to the Doctype parameter, the result set can be further constraint by the parameters Space Key, Space Keys, and Where.

Image Added

The sort order can be controlled by the Autocomplete Sort parameter. If not specified, the natural sort order is applied.

Template authors can also control the multiplicity – one or multiple values – and the tagging – are unknown names allowed or not (note that the macro editor is required to be restarted to apply changes to the following properties).

Image Added

For more information on how to use these parameters, please refer to Autocomplete.

Section

title	Display Document Property in Action

The Display Document Property Macros allow to select multiple documents. At least two characters are required to be entered to start the Autocomplete.

Image Added

Note Box

The feature "Pasting URLs" to a macro parameter value did not make it into the first release of Autocomplete.

The placeholder text "... paste URL" is therefore currently misleading. This will probably be available in one of the next releases.

Further constraints can be specified by the Autocomplete Constraints parameter. The sort order is specified by Autocomplete Sort. Again, if not specified, the natural sort order is applied.

Image Added

Section

title	Space Property Constraints

Currently there is only one space property to put constraints on the result set for names to be presented for Autocomplete: Autocomplete Active Constraint.

Image Added

This property specifies a constraint that must be met be names in the result set in addition to constraints defined by macro parameters. The property can be used to define that only names from documents that are in Iteration Released, Production, and Deprecated should be presented for selection. Please refer to Autocomplete Active Constraint for an example.

Note Box

title	Explaining the Where Clause

The Where clause shown above shows every doctype besides Event and Todo only as an option in an autocomplete if it is in Iteration Released, Production, or Deprecated. In case of an Event or Todo, the Iteration needs to be in Facade, Filled, Focused, Finished, or Released.

With this constraint only tags that are ready for use are rendered as options. On the other hand, events and todos are only options in case they are not completely done.

Code Block
( ($<Iteration>~(Released,Production,Deprecated) NOT $<Doctype>~(event,todo)) OR ($<Doctype>~(event,todo) AND $<Iteration>~(Facade,Filled,Focused,Finished,Released)) )

The contraint must be a valid Where clause fragment. For more information on queries with the projectdoc Toolbox, please refer to Search Tips.

Section

title	Caveats

Some tips on using Autocomplete that may save some time on occasion.

Section

title	Literally

Names are meant literally. In case a name of a document is changed, the names in macro parameter values are not changed. Neither in the Names parameter, nor in the Where or Sort By parameter.

This is by design. More information on this topic is found in the tip Changing Names.

Section

title	Doctypes missing

In case the Doctype parameter does not show all expected values, the doctype cache may be corrupt. In this case a user with appropriate access privileges needs to refresh the doctype cache.

Image Added

For more information on refreshing caches, please refer to Cache Refresh Actions.

Section

title	Parameters Coverage

Currently not all parameters of macros are fully covered by the Autocomplete Feature. While all macros support Names, Document, and Doctype Autocomplete, only one macro supports Document Property Name Autocomplete. Further Autocomplete support will be available in future versions of the projectdoc Toolbox.

The lack of support for a number of parameters may be not intuitive for some users. In case this troubles users, the Autocomplete Feature may be turned off by the administrators.

See Autocomplete for details on how to do this.

Section

title	Macro Parameter Panel

The support for setting macro parameters can be extended to the macro parameter panel. Confluence provides such a feature for the Status Macro, the projectdoc Toolbox for the Iteration Macro.

Image Added

Macro parameters for the Names parameter will be shown in a selection box. Currently the focus handling has some issues. Therefore this feature is turned off by default. Administrators may turn it on in case it supports the productivity of their users more than the quirky focus handling offends them.

See Autocomplete for details on how to do this.

Section

title	Tagging everywhere

In previous version of the projectdoc Toolbox tagging, the use of new names to support ad-hoc taxonomies, has been supported by all Names parameters. In the latest release of the projectdoc Toolbox and the related doctype add-ons, this support has been limited. Audience properties the roles, for Categories parameters the categories, and all Types properties referring to doctype types need to be defined in advance. We call this using prepared taxonomies. Only Tags properties are supporting ad-hoc taxonomies per default.

In order to go to the old state, there is a feature to support ad-hoc taxonomies for all Names parameters. See Autocomplete for details on how to do this.

Section

ignore-template-buttons	true
title	Subordinate Topics

Hide From Reader

Create from template

blueprintModuleCompleteKey	de.smartics.atlassian.confluence.smartics-projectdoc-confluence-space-core:projectdoc-blueprint-doctype-topic
buttonLabel	Create Topic

Display Table

doctype	topic
render-no-hits-as-blank	true
render-mode	definition
select	Name, Short Description
restrict-to-immediate-children	true
sort-by	Sort Key, Name

...

Section

title	References

Tour

render-no-hits-as-blank	true
render-as-definition-list	true
marker-column-property-name	Title
replace-title-with-name	true

Title

Short Description

Anchor

	footnote-1
	footnote-1

Erfolgsmuster: Strukturierte Faulheit

Article in a German magazine by Peter Hruschka und Gernot Starke "Erinnern kann Papier erheblich besser als Hirn" (translated as "Paper recalls much better than the brain").
Both authors share their insights in documenting software systems and software architectures by publishing their arc42 Template. There are plenty of resources on the internet. In case you are using the projectdoc Toolbox you may have a look at the arc42 Doctype Add-on which provides the arc42 Template for Confluence.

Anchor

	footnote-2
	footnote-2

We love to write documentation, don't we?

I admit I have heard the rumor that some people actually do not like to write or read documentation.

Section

title	Resources

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 3

New Version Current

Key

About

Keep up-to-date!

Powered by