Matt RaibleMatt Raible is a Web Developer and Java Champion. Connect with him on LinkedIn.

The Angular Mini-Book The Angular Mini-Book is a guide to getting started with Angular. You'll learn how to develop a bare-bones application, test it, and deploy it. Then you'll move on to adding Bootstrap, Angular Material, continuous integration, and authentication.

Spring Boot is a popular framework for building REST APIs. You'll learn how to integrate Angular with Spring Boot and use security best practices like HTTPS and a content security policy.

For book updates, follow @angular_book on Twitter.

The JHipster Mini-Book The JHipster Mini-Book is a guide to getting started with hip technologies today: Angular, Bootstrap, and Spring Boot. All of these frameworks are wrapped up in an easy-to-use project called JHipster.

This book shows you how to build an app with JHipster, and guides you through the plethora of tools, techniques and options you can use. Furthermore, it explains the UI and API building blocks so you understand the underpinnings of your great application.

For book updates, follow @jhipster-book on Twitter.

10+ YEARS


Over 10 years ago, I wrote my first blog post. Since then, I've authored books, had kids, traveled the world, found Trish and blogged about it all.

RECENT ENTRIES


Tag Cloud


abbie appfuse birthday denver family grails gwt jack java javascript jhipster jsf linkedin maven roller skiing softwaresummit spring springmvc struts2 travel trish vacation webframeworks wicket
« Integrating Facelets... | Main | Abbie and Jack -... »
Sunday October 15, 2006

Confluence installed for AppFuse 2.0 Documentation

The last item on the AppFuse Roadmap for 2.0 M1 is setting up the documentation system. I'm still undecided on whether Confluence or DocBook is a better system to use. However, I am certain that using a wiki to document an open source project is the lowest barrier to entry. For more on this topic, see my post from a month ago. In an ideal world, Confluence could be used as an authoring tool, and everything could be exported to DocBook for storing in SVN. Even better, pages that are "core" to AppFuse could be automatically saved in Subversion, and built using Maven's DocBook (or Confluence) support. Who knows, this is still new territory for me, and I feel like I'm losing momentum just thinking about it.

So far, I've installed Confluence 2.2.9 at http://dev.appfuse.org, but this will change in the coming weeks. I plan on eventually moving it to appfuse.org and leaving the demos on the demo.appfuse.org server. Hopefully there won't be too many 404s when we make the change.

Currently, I have Adaptavist's Builder installed for managing/manipulating themes. I've done some work with the default theme, but I think we can do much better. One cool thing I did find was the Page Tree Plugin that allows for Ajaxified tree menus like Stripes has.

Thanks to Atlassian and Adaptavist for the free product licenses.

Posted in Java at Oct 15 2006, 04:54:55 PM MDT 6 Comments
Comments:

Matt,

We had the exact same debate regarding which system to use as documentation for our products, i.e. Confluence vs DocBook. In the end, we went with Confluence (you can see the current doco here if you are interested). The biggest drawbacks of using Confluence are:

  • No support for branching, which makes it a bit harder to maintain documentation for multiple release streams (although this has been less of a problem in practice than I feared); and
  • Support for generating a printable copy, although decent, is not as strong as DocBook.

However, these are outweighed by the advantages:

  • Low barrier to entry (as you mention): it's just dead easy to get in there and work on the documentation.
  • Powerful search (not to be underestimated!).
  • Better navigation: provided you organise and cross-reference things well. An example of how <strong>not</strong> to do this is the WebWork doco, where you are always marooned on a page with minimal context to navigate to related information. We use the tree nav plugin to give better context (in particular visibility of sibling pages) and also cross-reference like crazy (which is made simple in a wiki).
  • The online copy is the primary format, which makes sense as it is the most popular way to access the doco. DocBook HTML output still has a bookish feel to me (although this is subjective).
The most important thing of course is the content, which is largely independent of the tool. Having said that, a low barrier to entry may also help encourage good content.

Posted by Jason Sankey on October 16, 2006 at 06:22 AM MDT #

Matty - no worries about the free license, but does this mean you owe me the car bombs now? :)

On the DocBook export, I wonder if this wouldn't be possible to do as a plugin. AFAIK DocBook is relatively close to HTML and we have an HTML exporter. I wonder if you couldn't do some cleanup / manipulation of the HTML output in code to give you DocBook? (I'm a complete DocBook newbie here)

m

PS I got the 'simple math question' wrong - can you make them easier for us Australians?

Posted by Mike Cannon-Brookes on October 17, 2006 at 01:18 AM MDT #

We faced exactly the same problem, as many open source developers do. We finally choose a drupal based solution, more because it's PHP based and at the time we chose we had no affordable J2EE hosting solution. The picture Jason give is the same for us, with one extra drawback: it's not possible to contribute documentation with patches. I'm still not convinced by either solution, and as I once said on my blog, I think it should be possible with current technologies to build a system with the best of both worlds. I'm currently studying the subject, and may prototype something in the near future. I'm still gathering use cases for the moment, and your previous post, Matt, is very interesting for that (as well as Jason comment on this post).

Posted by Xavier Hanin on October 17, 2006 at 12:17 PM MDT #

Hello. We've recently begun the switch from Docbook to Confluence. We decided, like you did, that ease of update was most important than the goodies that docbook provides. In the short term, we're looking at doing a PDF export to include in our distribution. In the longer term, we'd like to come up with some sort of XML export -> Docbook tool.

Anyway... two snags so far:

1) How are you getting the pagetree in a left menu? It looks like you are using a Builder theme. We'd like to do the same thing but without resorting to 3rd party themes or changes that won't migrate well on upgrades. Any ideas?

2) We want a Table of Contents to appear at the top of a space's PDF export. The AJAX pagetree doesn't do that obviously.

Anyway... please post or comment as you go so that your wisdom of how to manage docs in conluence makes it out. Searching for confluence and docbook at the same time turns up your posts, so I figure this is as good a spot as any to ask. :)

Posted by Amos on October 20, 2006 at 04:07 PM MDT #

hi, everyone first of all i would like to congratulate matt raibles and his team for the supa great work is appfuse, thats magic dudes. then i would ask if theres any way i can switch the menu system on appfuse so that i can get a tree menu just like u hav on the appfuse website? thanx in advance

Posted by antonio montana on December 26, 2007 at 01:18 PM MST #

You could use the expandable list from Struts Menu.

Posted by Matt Raible on December 26, 2007 at 05:05 PM MST #

Post a Comment:
  • HTML Syntax: Allowed