Agile development and Flare

[PBayne]

I was wondering if anyone is using Flare for documentation in an Agile development environment and what is the experience like? My company is looking at moving towards the Agile development model and I'm trying to get a handle on what to expect as well as try to get a jump start on some best practices.

Regards,
Pat

[ryan]

download the trial version of the tool and start building some content and see how it works for you in your first sprint, it should work just fine.

[PBayne]

Actually, I'm already using Flare. It's Agile development that's totally new to me.

[Andrew]

I don't think Agile will have any effect on Flare (or vice versa) at all. We just went scrum, and there's been no difference for me.

[RamonS]

In my experience Agile is what a good development team already does, except now it has a fancy name and you can waste money on consultants.

[KGaetz]

I've used Flare for Agile development and there are no problems. Can't say I'm impressed with Agile development, though. Another fad.

[akhoff]

I am currently using Flare to develop help in an Agile environment. The only difference is the speed at which the releases occur. Every 4 weeks we release a new version and it leaves a limited amount of time to see changes in the interface and update the help. It does not affect Flare specifically.

[RamonS]

Every four weeks a new version? What do the customers and especially sales say about that? Maybe in the industry you operate it is not a problem, but the places I worked at the goal was to reduce the number of releases and make release dates more predictable. First, we didn't have that and customers were confused why sales sold them old software. Where I work now, switching versions isn't that trivial and customers surely don't want to do that more than twice a year. Many only do it once a year and skip a version each time.
I hope you don't work on Google Chrome, has a new version twice a day with always the same old bugs.

[KGaetz]

I can't speak for others who have used it. I was on a team that was developing a new product. Development is not constant, but perpetual. ("scrums", I believe.) The goal for a given week might be something as small as a logon page.

I can't speak for developers, but as a tech writer, you are always "reacting" to a given situation in Agile development. I never really had time to plan anything before jumping in. Plus, I've always enjoyed the satisfaction of delivering the documentation at the end of a project and then catching my breath. With Agile (at least in my limited experience), as soon as you deliver release 1.0, you are immediately on to release 1.1. This is not a tech writer-friendly environment.

Maybe others have had a better experience?

[Andrew]

We typically have "maintenance" periods between scrum projects. So we'll have, say, a 12-week, 6-sprint project and then a month or so of maintenance time when the software is in beta.

However, in my experience, tech writers are on multiple scrum teams, not just one. I've been on as many as 3, which is brutal (waaay too many meetings). There are ways to mitigate the negative impact of multi-team authoring (such as a writer-only scrum team with its own backlog that treats other scrum teams as "consumers" of its "product," or having developers / QA do a lot more end-userish writing than they used to).

Some drawbacks to agile (from my experience):
- Too many meetings. Since I'm typically on multiple teams, and each team is about 1 day of meetings per week, resources and conflicts can get icky if you don't figure out some ways to reduce the load.
- Less time to plan, since you are pumping out (smallish) docs every couple of weeks.
- "Big picture" considerations in docs are harder, since any typical big picture feature will come from several disparate efforts, rather than all at once.

There are some very nice benefits to agile as well, though (also from my experience):
- Writers are integrated as a part of the process, not ignored until the end -- much less "oh wait, don't we need docs?" a few days before shipping, and much more "what do you need from us to get doc complete?"
- Our (documentation) products tend to be better-understood by the people in-house, which garners us more respect as professionals, and encourages developers, QA, etc. to take some ownership of documentation for features they put in.
- Reviews are generally better. Less "it looks good" and more actual feedback.
- It puts us in a position to be an excellent user advocate, a role to which we (should be) well-suited. Tired of development teams saying "oh, we'll just add that to the docs" when bad UI is pointed out? With agile, you're probably right there in the meeting, and can correct that horrible, horrible idea that bad UI can be corrected via doc.

[i-tietz]

Agile development is - according to my experience - excellent for developers because they can get rid of the tedious duty of planning and specification on any level.
Developers talk between themselves and know all sorts of things but don't write them down anywhere. And all that makes it tedious for QA and DOC departments: I look at the application and function X is one way. I describe it. A few weeks later I look at function X again and it looks and behaves different. I don't get to see sth like concepts of anything and on no level.

Wikipedia says it needs VERY disciplined developers to make information flow. Wikipedia also says that it's best used for customer sepcific software and that even that customer has to be "patient" and doesn't really know what he will get in the end.
My experience says that there is no such thing like a disciplined developer if there's no boss calling for the information to flow and the necessary discipline permanently. In fact quite a few developers think they are more like artists than professional producers, because they're "creative". And doing things they don't like to do (like writing concepts or specs) makes their muse leave for good - and the same applies to rules they're asked to follow.

And it hasn't got anything to do with the tool you're using - apart from source control software: It can come in quite handy to have older versions of what you've written - you might need it again, because sometimes develoeprs come back to the old ideas once they've tried to go a different way.

@Andrew:
For us it was exactly the other way round: 2 years ago there were concept meetings and written specs for new functions and DOC and QA had a chance to influence GUI and behavior. Now we don't do anything like that any more. Since our developers are drifting off into Agile Development they are a lot happier and QA and DOC are a lot unhappier (heard it at the assessment session for our COD). As said above: It needs a project manager (or COD) who makes rules and takes care for them being followed - without that: Take tranquilizer or find yourself another job.

[Andrew]

i-tietz:
Agile is not for the benefit of developers; it is for the benefit of users and, ultimately, the bottom line of the software company. It's about not taking 18, 24, 36, 48 months to get to market (from identifying the requirement to delivering the product). If your product lags requirements identification by several years (not uncommon), then you are completely unequipped to adjust to new trends, and are prone to deliver software that *isn't* what the user wants, and take a long time doing so to boot.

You should have a scrum master whose job is to ensure that the process remains disciplined. All of our teams have one. Some are better than others. Like any other such team (including waterfall development), the quality of the leadership goes far to determine the quality of the teamwork (and the result).

We used to be a waterfall dev house. If you got into meetings about designs or specs, then you are in a rather different position from me. We'd be stuck on the ass end of development, and about 40% of the time, no one told us what the functionality was. By the time it got to us, the developers involved had been away from the code for weeks or months (usually months) and didn't remember exactly what the stuff did, and *very few* business analysts updated the specs with changes that occurred during coding.

Neither agile nor waterfall are perfect. If you have the time / strategy to deal with the meetings, and some good scrum masters, I'll take agile over waterfall. Like anything else, you need the appropriate personnel and situation for either method to work best.

[i-tietz]

Far more info now - didn't sound like that before - see what a few opposing arguments can do?

I agree with RamonS: Maybe your customers are happy about updating every few weeks or months - consider yourself lucky! Most others are not. The normal computer user is not enthusiastic about changing anything.
A few examples:
1.
We even still have hundreds of customers that work with our over 10 year old MS DOS Software and are pretty mulish if our sales department tells them to swap to Windows Software, because we won't go on developing for DOS.
2.
Let me tell you about a really bizarre incident: I have watched somebody writing a serial letter with an ancient version of PageMaker on an even older Mac. Why? Because they never did it with Word ... the hardware is REALLY old and sometimes you can see the display rebuilding the picture line by line - understandable if you consider a PM document that has almost 200 pages ... So they prefer to need two days to write and print their almost 200 letters instead of two hours using Word. It's just like they wouldn't know what to do with the spare time. So they prefer to drive a nail into into the wall using a spoon, because they know how to handle that tool, but they don't know their way around with a hammer ...
3.
People who don't have anything to do with computer science or prgramming often don't even know that Windows XP doesn't necessarily has to look blue with the grass hills on the desktop.
4.
They don't even get rid of some software's "tip of the day", although they don't read it, because they don't want to change the default settings in any case. So they click on "Cancel" each time the open the software ...

The "normal" people out there are not keen on the 85th function - left with a choioce they would go for 50 functions that can be used intuitively. If you ask the actual users and not the ones that buy the software for them "handling" is higher in ranking than "number of functions" (study from 2009 - can't remember who from).

To cut a long story short: I'm still looking for the target group of Agile Development being invented to shorten the software life cyle ...
Cui bono? Only the developers who have more fun developing ...

[RamonS]

To cut a long story short: I'm still looking for the target group of Agile Development being invented to shorten the software life cyle ...
Cui bono? Only the developers who have more fun developing ...

Exactly! Agile development is something that makes developers happy, give those who have no role a new role as meeting organizer, and otherwise is a playground for consultants. Two years later folks figure out that they still have the problems due to bad technology decisions plus some more because it all had to agile and fast.
Where I work we could get away with one release per year and a few scheduled maintenance releases every other month, but the need for up to date state mandated reports dictates a biannual release cycle. And having a 6 month project cycle is about as agile as we can get with half a dozen developers and ten different products.
Then again, hitting the agile milestones doesn't mean that the result has to get released to the public. It all depends on what works and sustainably produces reliable product of high quality.
I like the spoon and nail analogy, if that what works for people, go ahead.

[Andrew]

To be clear: I'm not saying agile is right for everyone; I'm merely saying there are advantages and disadvantages, and in my case, the advantages have outweighed the disadvantages so far (and I've also tried to point out the purpose of agile).

In response to your previous points: it doesn't really seem that any of them address the end-user issue, which is:

A) Long lead time between releases, releases have lots and lots of features
B) Short lead time between releases, releases have only a few features

Which is better will probably depend to some degree on your market, but given that users can skip releases, I fail to see how A is superior in *any* way, whereas there are some distinct advantages to B.

[Andrew]

Exactly! Agile development is something that makes developers happy, give those who have no role a new role as meeting organizer, and otherwise is a playground for consultants. Two years later folks figure out that they still have the problems due to bad technology decisions plus some more because it all had to agile and fast.

Exactly wrong. Most of our developers *disliked* and *resisted* agile. It was a *business* decision, NOT made by developers. You're barking up the wrong tree.

Then again, hitting the agile milestones doesn't mean that the result has to get released to the public. It all depends on what works and sustainably produces reliable product of high quality.

Finally, something upon which we agree! And agile's milestones are *not* all released to the public. Agile milestones have nothing to do with releases at all. The idea is simply that you *could* release each milestone as it is reached. Doing so would be foolish in most cases, which is why very few teams I've heard of work that way.

[helen]

We're moving towards Agile development as well and so far it's working very well. We're a relatively small company (7 or so developers) and the decision to move to Agile was very much a management one rather than a development one. I much prefer it as the authoring process is tightly integrated and we are all one scrum team so I don't get swamped with meetings.

Some of our sprints are just defects, (doesn't make for an exciting showcase), however it gets them done so they don't drag on and the s/w is increasingly stable. These sprints do not have a Client release at the end unless a patch is released. Some are a mixture of client requirements and defects and some of those will be released to the client. The client is happy as they're getting releases which are simple to upgrade and contain functionality which they've either asked for or is useful to them in some way. The boss calls it "Agile in a waterfall model" - because we have some client requirements which are signed off months in advance and we just break the work down in sprint tasks.

As for Flare - it's going okay so far, I've had to adapt some of my processes to produce internal sprint documentation, but aside from that it's situation normal. In some ways it's easier because I'm involved from the start, I'm kept regularly up to date throught the daily scrums (where I can also identify blockers) and the documents are often smaller and more managable (although there is overhead in merging them into final Release Notes for client).

[PBayne]

Some drawbacks to agile (from my experience):
- Less time to plan, since you are pumping out (smallish) docs every couple of weeks.
- "Big picture" considerations in docs are harder, since any typical big picture feature will come from several disparate efforts, rather than all at once.

I'd be interested to find out how you cope with these drawbacks in particular, as I see them being issues in our implementation as well. Our doc set needs a re-org and in some cases a redesign but I won't have enough time to get it all done before we switch to agile.

[RamonS]

Exactly! Agile development is something that makes developers happy, give those who have no role a new role as meeting organizer, and otherwise is a playground for consultants. Two years later folks figure out that they still have the problems due to bad technology decisions plus some more because it all had to agile and fast.

Exactly wrong. Most of our developers *disliked* and *resisted* agile. It was a *business* decision, NOT made by developers. You're barking up the wrong tree.

Well, my experiences are different then. I worked on agile teams and it was the developers who pushed that through, the same way everything had to be DotNet and application servers had to die because Microsoft said so (which meant stuffing all the code into the database as stored procedures, which in some cases is the right thing to do, but not in all cases).
In the end it doesn't matter who makes the decision, but I get the impression that way too often agile methods are used just because everybody else is using this buzzword or because there is the ill-fated believe that all problems magically go away when using agile methods.

If it works for some groups then who am I to say that it doesn't.

[Andrew]

Some drawbacks to agile (from my experience):
- Less time to plan, since you are pumping out (smallish) docs every couple of weeks.
- "Big picture" considerations in docs are harder, since any typical big picture feature will come from several disparate efforts, rather than all at once.

I'd be interested to find out how you cope with these drawbacks in particular, as I see them being issues in our implementation as well. Our doc set needs a re-org and in some cases a redesign but I won't have enough time to get it all done before we switch to agile.

We don't have a systematic way to deal with them. Typically, we have nothing to do early in a sprint -- there is no code to test / doc yet, so we start fleshing out bigger concepts, passing them back and forth with the product owner(s) and making sure we understand the business cases. Basically, during the first few days of a sprint where we're doing some of the larger stuff, I'll try to come up with a rough outline of what this should help our users do. This gets me a halfway decent overview, "why would I want to use this feature," and a list of tasks I'll need to doc. I then have to "look ahead" in the uncommitted backlog or at other upcoming stories in the current sprint, and try to see if what I'm doing will be combined with something else, and write in such a way that I hope to be able to drop the other thing in fairly easily. It doesn't always work out, and it's not all that easy.

Redesigning docs during a scrum process...well, you'd better be either over-resourced or have downtime between sprints. Or get the redesign as part of the backlog effort.

Some other teams I've seen take docs / DBA and each creates its own scrum team, complete with its own backlog, and acts as a sort of "server" to the "client" of your dev scrum teams. Your sprints lag a week or so behind theirs (and may be shorter), and their doc requirements go into your backlog (as do your own projects, such as redesigns, user testing, maintenance on older doc, etc.), they are prioritized, and you work from that.

I've also seen times when other scrum team members pitch in and help with docu, usually by writing out how all the stuff they've done works, and sometimes getting screen caps, etc. That can speed up the end-of-sprint crunch on doc, and give you a bit more breathing room organizing and revising the content.

[Andrew]

In the end it doesn't matter who makes the decision, but I get the impression that way too often agile methods are used just because everybody else is using this buzzword or because there is the ill-fated believe that all problems magically go away when using agile methods.

That's not what *I* said, though. No one should think agile magically removes problems. It ameliorates some problems inimical to waterfall methods (slow time-to-market, software that fails to meet customer expectations despite detailed planning), and introduces problems of its own (resources less efficient due to meetings, backlash from culture change, greater difficulty delivering very large changes or additions to functionality). It's a matter of what is needed in the particular situation. In our situation, we were very much hampered by waterfall, because we couldn't react quickly to changing customer demands and markets, we would spend 3 years or more spec'ing, coding and testing something only to deliver it and find that it wasn't *really* what the customers wanted (despite having detailed specifications approved by the customers -- because the customers leave out steps, or important bits of information that they assume without even realizing it, or just plumb didn't understand the problem they thought they were trying to solve).

[i-tietz]

slow time-to-market

"Haste makes waste." - that's my experience. Developers realease a test master with a new function. I look at it (cos I have to do the docs) and notice bugs. I send a mail to the developer to tell him it doesn't work as expected. He asks me how old my master is, because it works in his master. Since I know I'm working with the newest one I ask him to show me that it really works for him. I find out that he choses different settings ... settings with which the observed behaviour is correct, but not with others.
What sort of test is that? What sort of plan is that? He should have thought about all the other cases too - why hasn't he? Because they don't do specs any more, they don't think about what they're going to do thoroughly anymore as they would have to do for writing a concept or specs. They start hacking almost straight away - only talk about things.
As Wikipedia says: It takes good and forceful project management and disciplined developers.
If you don't have either it will cause you problems.

@Andrew:
Even if everything's working fine: How do you write the conceptual doc? If you don't get to see the "opus" in its whole before it's finally released - how do you explain connections and background? Or do you make do with describing controls? Or do you insert that knowledge and apply conditions for each concept and work with targets including concepts A, C and D and exclude all others?

[Andrew]

Regarding "haste makes waste" -- this is a useless truism without a definition of haste. If you're worried that things get missed in the shorter timeframes of agile: yes, that is a possibility, but also remember that the "chunks" worked on for any particular sprint are comparatively small.

Even if everything's working fine: How do you write the conceptual doc? If you don't get to see the "opus" in its whole before it's finally released - how do you explain connections and background? Or do you make do with describing controls? Or do you insert that knowledge and apply conditions for each concept and work with targets including concepts A, C and D and exclude all others?

That's an excellent question. You write what you can, when you can. Sometimes, it's fairly easy, and the user-ramifications / concepts / etc. of the software during the sprint is readily apparent, or the functionality is completed in a single sprint, so then the docu is pretty easy. Sometimes things are not as easy, and during the last couple of sprints in a project, when all the pieces are coming together, you have to allot more doc hours to refactoring docu for those things. This is something we as writers need to communicate to our teams, so they understand the resource crunch, and can help out. Our developers and QA can help by writing a "post-hoc specification" of how the stuff works for that sprint, and that means we save a lot of time asking questions, figuring out how it works, etc.

If I have partially-written concepts, etc. how I handle them depends on the project. If I'm disciplined, and the project is such that I have well-defined stuff, I condition anything that didn't actually get delivered so that docu accurately reflects whatever is done done. The reality is that I sometimes take the less disciplined approach and just leave it all there, because I know we're not shipping for months. I shouldn't do that, as it is antithetical to the agile process we use. I just haven't completely adjusted my processes to scrum in that manner yet. I'm glad you brought it up; I really need to get in gear on that score.

[i-tietz]

Which is better will probably depend to some degree on your market, but given that users can skip releases, I fail to see how A is superior in *any* way, whereas there are some distinct advantages to B.

Maybe you're producing individual software. With a patient customer Agile might work then.

If you produce standard software you don't only have to do testing for the new function but also for the integrated pack: Cross links and side effects are extremely relevant. Are you you trying to tell me that in Agile testers will be given enough time to test all connected functionalities too?
And what if the functionality is easy to program but needs extensive description? Are you trying to tell me developers would wait for DOC or QA to finish before the next "sprint" starts?
Nothing to do at one time, too much to do at another ... "efficient" is somewhat different ...