MadCap Software Forums

Hi,

I have been using Flare for my own product development work to manage all product development documentation (plans, specifications, designs, etc). I got tired of writing the same words in many documents. I have used Flare for Agile Development and Process Improvement projects. Recently, I have prototyped an architecture description document that needed a lot of cross-reference links and have used the Relationship tables to manage all of the relationships. This exceeded my expectations.

I am finding that when i work with development teams (other companies) they seem to be using Wikis in a similar way. I have not seen wikis that do snippets, variables, or relatioship tables ... so I think development teams might be missing something.

Do you know any other product development teams using Flare for all of their product documentation ... not just help or user information?

I'm curious to know their experience and also understand any tradeoffs between a wiki or the Flare approach?

Any thoughts or feedback appreciated!!

Regards, Bruce

I thought Agile doesn't document anything. The hard core Agilers I know insist that source code is all the documentation that is needed. I disagree. That said, you might be on to something, but Wikis are much easier to set up and use. And they tend to look more like whiteboards, which warms the hearts of the die-hard Agilers.

Many thanks for the feedback ... I'm curious to learn more about your wiki impressions ... the white board concept is quite interesting.

Re: Agile ... there are a number of schools of agile...

One is the DSDM Atern school (similar to EVO) with a bit of up front documentation prior to development time boxes. DSDM does tend to have a bit more documentation about the business, architecture, requirements, etc ... there are a number of chunks of text that can be reused. I tend to do a bit more documentation (thus flare) to be able to hand over to other teams.

Another is the scrum school ... this school needs to identify and track of stories (short term and long term). A developer (maybe a pair) take responsibility for a story to carry out detail design, coding, test and integration until the story is complete. ... however, as with any of the agile schools, there is a lot of capturing learnings around the tools used for development and the use of the system. Scrum tends to be more interactive with post-its and visual tracking.

In my experience, it takes more disciplines to do agile than other development approaches.

The architecture area is a bit different as this area integrates models with text and generally needs a lot of links. These documents tend to survive across multiple projects or versions and need version tracking. The more these flow through development projects the better. This is the area I'm looking at now ... finding a balance between model building tools (images and text) and flare type tools to package information in multi-output modes. ... I'm prototyping with Flare in this area.

Thanks again.. Any other thoughts appreciated!!

Regards, Bruce

Thanks for pointing to "DSDM Atern", strikes me as the more reasonable approach than Scrum. Scrum works OK for products that have a life time of 12 to 18 months. In our case we design for 5 to 7 years with ongoing development. I have no idea how a team that may not have any original members can wrap their mind around decisions made years ago without documentation. In our case customers expect one or two releases a year, so the rapid release nature doesn't get us any benefit. OK, so much now for my digression....

I have taken a look at DSDM Atern from a documentation point of view and it does fit nicely in Flare. Documents can be produced if necessary (PDF or Word) or they just end up as sections on the TOC. (with a number of common snippets underneath) ... in webhelp or CHM.

I have been working with an organization that thinks they do DSDM Atern ... however, they start over for each project. I'm now working to shift them into a single project (product) framework ... with multiple business owners ... with a continuous stream of timeboxes that can startup quickly. (It's a big website with multiple business owners: Website = Product = one project; with prioritized requirements allocated to timeboxes). There is a single website architecture / tools and single business definition) and single development process / approach.

A nice fit for a single Flare project ... to provide the context for multi-timebox projects ... that may extend for a long time.

Thanks again for your thoughts ... Regards, Bruce

Dear Bruce,

I am a business analyst and like you have worked with many projects using many methodolgies but essentially producing the same stuff, or at least similarly structured information. I am interested in how you used relationship tables since I haven't ventured into this area, but reading about it now I think it would suit my needs very well because I am documenting Indtroductory Ideas and concepts, processes and "how to" instructions for each process. At my current client they have not got any business modelling software and therefore I have diagrams and words to organise and aviod duplication.

Do you have any quick hints about using this facility?

Thank you............................... liz

Here are some quick hints regarding relationship tables (at least things I was surprised to find):

1) A project can have many relationship tables ... so make sure that a single table focuses on a single type of relationship
2) I ended up using simple two or three column tables (from, to, other related links(if necessary))
3) Keep the primary column to a single link ('from' = 1 entry, 'to' may have more than one; I have some 1-1 tables)
4) I kept any additional columns (3rd column) with the back refrence disabled (so only shows up with the 'from' column)
5) I made a snippet to hold the place where the relationships would show (so they all looked the same when displaying links and can be changed in one place).
6) Make all items to be used in the table simple topics with a single type of information (more topics than I expected ... but worth the time).

Relationship tables save a significant amount of time when changes are required or new items are added... it's just another row in a table or a link in a column.

As a result of this experience, I also started to use the index, and concepts a bit more. These are also useful to group topics that display in a list (like a list of external standards, etc)

I'm interested to hear how you use the tables / links in your project.

Hope this helps!! Regards, Bruce