Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Document Properties Marker
hidetrue
render-asdefinition-list


Short DescriptionThe projectdoc Toolbox supports agile teams in writing project documentation collaboratively. This is an introduction to use cases for and features of the projectdoc Toolbox.
Doctypeprojecthide
NameThe projectdoc Toolbox for Atlassian Confluence
Tags
Tag List
namesConfluence Add-on

Logo
hide
Sort Keyhide
support-emailsupport@smartics.dehide
documentation-json-urihttps://www.smartics.eu/confluence/download/attachments/12156954/docmap.json?api=v2hide
extract-short-description-from-metadata-tabletruehide
render-metadata-asdefinition-listhide



Content Layer
background-sizecover
background-imageIsarBaumeFlussAnton.jpg
background-positionbottom center
id778797066


Content Column
background-colortransparent
width100%
id778797071


Content Block
background-colortransparent
id778797075
height310px


HTML Wrap
classsmartics-image-text

projectdoc


HTML Wrap
classsmartics-image-text

Agile Documentation
in your Confluence



HTML Wrap
classsmartics-image-tagline

Lost in wiki space? Blank-Wikipage-Syndrome?
Where to add? How to find? No fun anymore?





Content Layer
id1238483259
positiontop
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100%
id1238483262


Content Block
background-colortransparent
id1238483264
positiontop
classsub-menu




Content Layer
background-colortransparent
id1044244661
classsmartics-hide


Content Column
width100.0%
id1044244667


Content Block
id1044244673

Display List
doctypedocsection
list-typedefinition
sort-byName
render-short-descriptiontrue
space-keyPDAC




Content Layer
background-colortransparent
id191643293
classsmartics-large smartics-layer bright


Content Column
width100.0%
id191643295


Content Block
id191643297

Enhance your Documentation Experience !

The projectdoc Toolbox supports agile teams in writing documentation collaboratively




Content Layer
id183771004
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width100.00001%
id183771011


Content Block
id183771027
classsmartics-highlight-block blue


Content Marker
idwhy-should-i-care

I have 1 minute! Why should I care?





Content Layer
id205606541
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width50%
id205606547


Content Block
nametheproblem
id205606555
classsmartics-highlight-block blue
height335px


Content Marker
idthe-problem

The Problem

Lost in wiki space? Blank-Wikipage-Syndrome? Where to add? How to find? No fun anymore?

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.

And step by step

Content Marker
csswhite-div
  • information is more difficult to find
  • new information is more difficult to add





Content Column
background-colortransparent
width50.0%
id205606550


Content Block
namethesolution
id205606558
classsmartics-highlight-block blue
height335px


Content Marker
idthe-solution

The Solution

projectdoc tackles these issues by adding structure to

Content Marker
csswhite-div





Content Layer
id202653551
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width33%
id202653559


Content Block
nameoneminute
id202653573
classsmartics-highlight-block red

If you have 2 minutes ...

Action Button
padding7px 36px 7px 36px
linkHOMESPACE:projectdoc Introduction Video
textWatch the introduction!
titleWatch our video introduction!
classsmartics-call2action color



Content Column
background-colortransparent
width33.5%
id202653562


Content Block
namemoreminutes
id202653577
classsmartics-highlight-block yellow

If you have some more minutes ...

Action Button
padding7px 36px 7px 36px
textRead the Introduction!
titleRead our introduction!
classsmartics-call2action color
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-Whatisprojectoc



Content Column
background-colortransparent
width33.5%
id206013586


Content Block
namemoredetails
id206013592
classsmartics-highlight-block green

More Details? Browse the Manual!

Action Button
padding7px 36px 7px 36px
textGet started!
titleBrowse the Online Manual! Learn about Macros and Doctypes!
classsmartics-call2action color
urlhttps://www.smartics.eu/confluence/display/PDAC1/projectdoc+for+Confluence+V1




Content Layer
id1231
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width100%
id1463338493
class1232


Content Block
background-color#022F5C
id1233
classsmartics-highlight-block blue


Content Marker
idhighlights-and-features

Highlights and Features

List of features provided by the projectdoc Toolbox

Action Button
padding7px 36px 7px 36px
linkPDAC1:Features
textLearn more!
titleLearn about highlights and features and how users take advantage of them
classsmartics-call2action color





Content Layer
id1463338486
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width100%
id1463338493


Content Block
background-color#022F5C
id1463338495
classsmartics-highlight-block blue


Content Marker
iduse-cases

Use Cases

A collection of use cases for the projectdoc Toolbox

Action Button
padding7px 36px 7px 36px
textLearn more!
titleLearn about use cases and how projectdoc supports them
classsmartics-call2action color
urlhttps://www.smartics.eu/confluence/display/PDAC/Use+Cases




Content Column
background-colortransparent
width100%
id1463338493


Content Block
background-color#022F5C
id14633384951
classsmartics-highlight-block blue


Content Marker
idshow-cases

Show Cases

A collection of show cases built with the projectdoc Toolbox

Action Button
padding7px 36px 7px 36px
textLearn more!
titleLearn about show cases built with the projectdoc Toolbox
classsmartics-call2action color
urlhttps://www.smartics.eu/confluence/display/PDAC/Show+Cases





Content Layer
id148687805
classsmartics-large smartics-layer bright


Content Column
width100%
id148687819


Content Block
background-color#022F5C
id148687820

Try it now!

The projectdoc Toolbox and free add-ons are available on the Atlassian Marketplace




Content Layer
id907041086
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100%
id907041088


Content Block
background-colortransparent
id1223238434

projectdoc in Action

Get an impression on how to work with the projectdoc Toolbox for Confluence!

Please check the list of topics that may be relevant for your evaluation process!

Compare some native Confluence macros with macros of the projectdoc Toolbox!


Content Block
background-colortransparent
asynchronous-loadtrue
id907041090

 




Content Layer
id1396069772
classsmartics-large smartics-layer bright


Content Column
width100%
id1396069774


Content Block
id1396069776

Concepts

The main concepts of the projectdoc Toolbox




Content Layer
id1056552218
classsmartics-large smartics-layer


Content Column
width50.0%
id1056552224


Content Block
id1056552228
classsmartics-large smartics-layer
height390px


Content Marker
idproperties-and-sections

Properties and Sections


Document types define properties and sections a document instance may provide



Content Block
id20150601130
classsmartics-large smartics-layer dark

Action Button
padding7px 36px 7px 36px
textLearn more
titleLearn more
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-PropertiesandSections



Content Column
width50.0%
id1394818737


Content Block
id1056689601
classsmartics-large smartics-layer
height390px


Content Marker
iddocument-types

Document Types


Documents, easily related by their type, build a web of information



Content Block
id20150601150
classsmartics-large smartics-layer dark

Action Button
padding7px 36px 7px 36px
textLearn more
titleLearn more
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-DocumentTypes




Content Layer
id1395127797
classsmartics-large smartics-layer


Content Column
width50.0%
id1395127803


Content Block
id1056970031
classsmartics-large smartics-layer
height440px


Content Marker
idguided-writing-clutter-free-reading

Guided Writing &
clutter-free Reading


Doctypes provide a location where authors put information of a given type, but empty sections or unset properties are not rendered on the page



Content Block
id20150601230
classsmartics-large smartics-layer dark

Action Button
padding7px 36px 7px 36px
textLearn more
titleLearn more
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-GuidedWritingandclutter-freeReading



Content Column
width50.0%
id1395153298


Content Block
id1057012609
classsmartics-large smartics-layer
height440px


Content Marker
idsingle-sourcing-and-transclusion

Single Sourcing and Transclusion


Modularize your documentation and transclude it from everywhere



Content Block
id20150601250
classsmartics-large smartics-layer dark

Action Button
padding7px 36px 7px 36px
textLearn more
titleLearn more
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-SingleSourcingandTransclusion




Content Layer
id1395217608
classsmartics-large smartics-layer


Content Column
width50.0%
id1395217610


Content Block
id1056990060
classsmartics-large smartics-layer
height390px


Content Marker
iddynamic-lists

Dynamic Lists


New documents are automatically listed on existing pages with dynamic lists



Content Block
id20150601330
classsmartics-large smartics-layer dark

Action Button
padding7px 36px 7px 36px
textLearn more
titleLearn more
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-DynamicLists



Content Column
width50.0%
id1395407599


Content Block
id1057261513
classsmartics-large smartics-layer
height390px


Content Marker
idmacro-structures

Macro Structures


Templates define the micro structure, the organisation of documents within a space, using home- and index pages, defines the macro structure



Content Block
id20150601350
classsmartics-large smartics-layer dark

Action Button
padding7px 36px 7px 36px
textLearn more
titleLearn more
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-MacroStructures




Content Layer
id1395034408
classsmartics-large smartics-layer


Content Column
width100.0%
id1395069121


Content Block
id1057287435


Content Marker
idspace-hierarchies

Space Hierarchies


Organize your information in spaces that relate to each other



Content Block
id20150601430
classsmartics-large smartics-layer dark

Action Button
padding7px 36px 7px 36px
textLearn more
titleLearn more
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/display/PDAC/projectdoc+Introduction#projectdocIntroduction-SpaceHierarchies




Content Layer
id198398422
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100%
id198398424


Content Block
background-colortransparent
id198398426

Agile Documentation




Content Layer
id198898286
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100%
id198898288


Content Block
background-colortransparent
id198898290

Agile documentation is about essential and valuable information that teams create just-in-time.

The projectdoc Toolbox supports agile teams creating and maintaining documentation. It provides templates and tools to improve the collaboration of team members.

Action Button
padding7px 36px 7px 36px
linkADOC:Agile Documentation
textMore on Agile Documentation
titleInformation on agile documentation: from values to principles and practices. A set of actionable tools for team communication.
classsmartics-call2action bright


With projectdoc your wiki is




Content Layer
id199797694
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width33.333332%
id199797699


Content Block
background-colortransparent
border-color$tertiaryColor
border-width1
id199797703
border-stylesolid

easier to write



Content Column
background-colortransparent
width33.333332%
id200023659


Content Block
background-colortransparent
border-color$tertiaryColor
border-width1
id200023661
border-stylesolid

easier to reuse



Content Column
background-colortransparent
width33.333332%
id199991102


Content Block
background-colortransparent
border-color$tertiaryColor
border-width1
id199991104
border-stylesolid

easier to search




Content Layer
id201579416
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width33.333332%
id201579420


Content Block
background-colortransparent
border-color$tertiaryColor
border-width1
id201579428
border-stylesolid

easier to extend



Content Column
background-colortransparent
width33.333332%
id201579422


Content Block
background-colortransparent
border-color$tertiaryColor
border-width1
id201579431
border-stylesolid

easier to navigate



Content Column
background-colortransparent
width33.333332%
id201579424


Content Block
background-colortransparent
border-color$tertiaryColor
border-width1
id201579433
border-stylesolid

easier to read




Content Layer
id591858234
classsmartics-large smartics-layer dark


Content Column
width100%
id591858235


Content Block
id591858236

Project Documentation




Content Layer
id191912293
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width50.0%
id198846039


Content Block
background-colortransparent
id198846040

projectdoc supports all four quadrants of the documentation space. The PDAC1 provides macros, page and space templates to help you and your team in organizing documentation in multiple Confluence spaces (if needed to).

On agile projects you typically invest in the quadrants 3 and 4. But depending on your team and customer, documents from the two other quadrants may also help you stay productive.



Content Column
background-colortransparent
width50.0%
id200740120


Content Block
background-colortransparent
id200740122




Content Layer
id591780859
classsmartics-large smartics-layer dark


Content Column
width100%
id591780860


Content Block
id591780861

Your Information in your Wiki




Content Layer
id591587720
classsmartics-large smartics-layer dark


Content Column
width50.0%
id591587755


Content Block
id591587756




Content Column
width50.0%
id591640148


Content Block
id591640149

projectdoc is not only for project documentation. It is a tool to organize any information in your wiki.

While it supports modular documentation to enhance team collaboration, there are also use cases for individual knowledge workers.

One example is our add-on to create journals or diaries.

Employ projectdoc to create workspaces for collecting interesting information quick-and-dirty or for organizing your information carefully in topic spaces.




Content Layer
id192177646
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100.0%
id192177648


Content Block
background-colortransparent
id192177650

Action Button
padding7px 36px 7px 36px
linkPDAC1:projectdoc Toolbox
textGet started with projectdoc
titleGet started with projectdoc for Confluence
classsmartics-call2action bright




Content Layer
background-colortransparent
id1056366303
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width100.0%
id1056366312


Content Block
background-colortransparent
id1056366317

Macros and Templates




Content Layer
background-colortransparent
id193540668
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width100.0%
id193540671


Content Block
background-colortransparent
id193540675

The projectdoc Toolbox for Confluence provides macros and templates to help you structuring your documentation. This keeps you concentrated on the content valuable for your users and the developing teams by removing distractions such as

  • Where should I place my document?
  • What information is expected from me for a document of type "(...)" ?
  • How should I structure my document?
  • Which meta information about my document is relevant? How to write it down?
  • How will the target audience find my document?

The Tour for Document Authors provides in-depth information on working with the PDAC1.




Content Layer
background-colortransparent
id193656731
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width100.0%
id193656733


Content Block
background-colortransparent
id193656735

Action Button
padding7px 36px 7px 36px
linkPDAC1:projectdoc Toolbox
textGet started with projectdoc
titleGet started with projectdoc for Confluence
classsmartics-call2action




Content Layer
id193490473
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100.0%
id193490476


Content Block
background-colortransparent
id193490480

Custom Template Suite




Content Layer
id193697065
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100.0%
id193697068


Content Block
background-colortransparent
id193697070

While the projectdoc Toolbox for Confluence provides a basic set of templates to start with, it is easy for development teams to define their own template suite as a blueprint add-on. Use the free and open-source templates as a basis for your team intern templates!

The Tour for Template Authors gets you started with defining your own templates for the projectdoc Toolbox. Learn the basic concepts of the projectdoc Toolbox!




Content Layer
id193711844
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100.0%
id193711847


Content Block
background-colortransparent
id193711849

Action Button
padding7px 36px 7px 36px
linkPDAC1:projectdoc Toolbox
textGet started with projectdoc
titleGet started with projectdoc for Confluence
classsmartics-call2action bright




Content Layer
background-colortransparent
id111000
classsmartics-large smartics-layer bright


Content Column
background-colortransparent
width100.0%
id1056366312
class111001


Content Block
background-colortransparent
id197999191

News on projectdoc

HTML
<style>
.blog-item .blog-title {
	color: #5b80ad;
}
.blog-post-list li.blog-item {
    border-bottom-color: #5B80AD;
}
.blog-post-list li.blog-item:hover .blog-title {
	color: #f9f9f9;
}
.blog-item .blog-title * {
}
.blog-item .blog-item-date {
	color: #5B80AD;
    display: inline;
    float:right;
 }
 </style>

Blog Posts
max15
spacesBLOG
sortcreation
reversetrue
contenttitles
labelsprojectdoc

Action Button
padding7px 36px 7px 36px
textRead more
titleGet in touch
classsmartics-call2action
urlhttps://www.smartics.eu/confluence/label/BLOG/projectdoc




Content Layer
id197999186
classsmartics-large smartics-layer dark


Content Column
background-colortransparent
width100%
id197999189


Content Block
background-colortransparent
id1110003

Questions?

You have questions, need to discuss documentation topics, or would like to suggest new features for projectdoc?


Content Block
background-colortransparent
id1110006

Action Button
padding7px 36px 7px 36px
textGet in touch
titleGet in touch
classsmartics-call2action bright
urlmailto:info@smartics.de?subject=Get%20in%20Contact




Content Layer
background-colortransparent
id1056571815
classsmartics-large smartics-layer


Content Column
width100.0%
id1056571818


Content Block
id1056571821

Quotes on Documentation




Content Layer
background-colortransparent
id193821012
classsmartics-large


Content Column
width100.0%
id193821014


Content Block
id193821016

A word of warning...

Every document is a liability. Make sure that every document you write is worth its investment. Write sustainable documentation that document the why instead of the how. Do not head for perfection. Strive for automation and living documentation! This will make your documentation sustainable, fun and increase the return of invest.

Here are some quotes concerning documentation and writing that may be your guide:




Content Layer
background-colortransparent
id191841124
classsmartics-large


Content Column
tabbed-blocksfalse
width100.0%
id191841134


Content Block
background-colortransparent
nameWilliam Zinsser
id191841144


Quote External
authorWilliam Zinsser
author-urihttp://www.williamzinsserwriter.com/
sourceOn Writing Well

Writing is hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time. Remember this as a consolation in moments of despair. If you find that writing is hard, it's because it is hard. It's one of the hardest things that people do.



Content Block
nameScott Ambler
id191841141


Quote External
source-urihttp://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm
authorScott Ambler
author-urihttp://www.ambysoft.com/scottAmbler.html
sourceBest Practices for Agile/Lean Documentation

Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.



Content Block
nameMike Clark
id192590444


Quote External
source-urihttp://pragprog.com/book/auto/pragmatic-project-automation
authorMike Clark
sourcePragmatic Project Automation: How to Build, Deploy, and Monitor Java Applications

Automation also reduces the need for documentation.



Content Block
nameRebecca Wirfs
id192573411


Quote
source-wiki-pageWirfs-Brock2003

Design is an inherently messy process, and along the way many descriptions are discarded after serving their purpose.



Content Block
nameRon Jeffries
id1056388317


Quote External
source-urihttp://xprogramming.com/xpmag/expDocumentationInXP
authorRon Jeffries
author-urihttp://en.wikipedia.org/wiki/Ron_Jeffries
sourceEssential XP: Documentation

Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else. Trust yourselves to know the difference.



Content Block
nameJoe Ottinger
id193252920


Quote External
source-urihttp://www.theserverside.com/tip/Hand-pick-the-right-Java-library-for-your-software-project
authorJoe Ottinger
sourceHand pick the right software project for your situation

It’s probably fair to say that poor documentation kills more libraries and tools than any other issue.



Content Block
nameEric Evans
id193266477


Quote External
authorEric Evans
author-urihttp://www.amazon.com/Eric-Evans/e/B001KDCO2I
sourceDomain-Driven Design

But making written documents that actually help the team produce good software is a challenge.





Content Layer
background-colortransparent
id1056671874
classsmartics-large


Content Column
columnalternate
width33.333%
id1056671882


Content Block
id1056671896


Quote External
authorGernot Starke
original-quote Erinnern kann Papier erheblich besser als Hirn.
know-notejavamagazin, 10/2010, s. 56f
author-urihttp://www.gernotstarke.de/

Paper is better in remembering than your brain.


Quote
source-wiki-pageJacobson2011

Successful programs not only offer clear documentation but they also recognize that developers don't have a lot of time (or inclination) to sit down and read it.


Quote External
source-urihttp://www.leansoftwarearchitecture.com/
authorJames O. Coplien
author-urihttps://sites.google.com/a/gertrudandcope.com/www/jimcoplien
sourceLean Architecture: for Agile Software Development

Even a whiteboard diagram, or a CRC card, is documentation: the goal isn't to avoid documentation, but to document just the right things in just the right amount.


Quote External
source-urihttp://xprogramming.com/xpmag/expDocumentationInXP
authorRon Jeffries
author-urihttp://en.wikipedia.org/wiki/Ron_Jeffries
sourceEssential XP: Documentation

If there is a business need for a document, the customer should request the document in the same way that she would request a feature: with a story card. The team will estimate the cost of the document, and the customer may schedule it in any iteration she wishes.




Content Column
columnalternate
width33.333%
id1056671885


Content Block
id1056671899


Quote External
source-urihttp://www.goodreads.com/quotes/4957-the-difference-between-the-right-word-and-the-almost-right
authorMark Twain
author-urihttp://en.wikipedia.org/wiki/Mark_Twain
sourceThe Wit and Wisdom of Mark Twain

The difference between the right word and the almost right word is the difference between lightning and a lightning bug.


Quote External
source-urihttp://www.startupbook.net/
authorRob Walling, Mike Taber
sourceStart Small, Stay Small: A Developer's Guide to Launching a Startup

Documenting repeatable processes for anything you will do more than once is essential to your sanity.


Quote External
source-urihttp://pragprog.com/book/auto/pragmatic-project-automation
authorMike Clark
sourcePragmatic Project Automation: How to Build, Deploy, and Monitor Java Applications

Automation will give you back something you don't have enough of: time.


Quote External
source-urihttp://databaserefactoring.com/
authorScott W. Ambler, Pramod J. Sadalage
sourceRefactoring Databases

The cleaner your design, the less documentation you require.


Quote External
authorEric Evans
author-urihttp://www.amazon.com/Eric-Evans/e/B001KDCO2I
sourceDomain-Driven Design

Rather than a diagram annotated with text, I write a text document illustrated with selective and simplified diagrams.




Content Column
columnalternate
width33.333%
id1056671889


Content Block
id1056671903


Quote External
source-urihttp://xprogramming.com/xpmag/expDocumentationInXP
authorRon Jeffries
author-urihttp://en.wikipedia.org/wiki/Ron_Jeffries
sourceEssential XP: Documentation

XP is designed to use face to face human communication in place of written documentation wherever possible. Effective conversation is faster and more effective than written documentation. When you bring people together, they need less paperwork.


Quote External
source-urihttp://thenewkingmakers.com/
authorStephen O'Grady
author-urihttp://thenewkingmakers.com/bio/
sourceThe New Kingmakers

MindTouch, for example, argues that documentation represents potential profit, rather than a cost, because it's not a finely crafted mess of marketing jargon — documentation is legitimately useful from a developer's perspective. As such, it can help you build and sustain communities!


Quote
source-wiki-pageJacobson2011

Intuitiveness does have limitations, however; that’s when developers need documentation. [...] Reading documentation is a last stop rather than a first stop for many.