1) Arya, the documentation lead, pushes for documentation tasks to be formally included in an organization's agile project management process through the use of feature sheets, as large documentation projects are currently not properly planned or resourced.
2) After successfully making the case that rewriting a technical guide requires as much effort as a software feature, Arya works with the product manager to create a feature sheet for the documentation work.
3) With project artifacts now reflecting the documentation task, the team is committed to the work and provides support through the regular process, allowing Arya to successfully complete the updated guide.
Water Industry Process Automation & Control Monthly - April 2024
Case study—Establishing product documentation as practice in agile
1. 1
Establishing documentation as a practice in
Agile
By Sudhir Subudhi, Lead Technical Writer, Process Expert
Jun 11, 2014
Arya walked up stairs fast, thinking not to be late in
the meeting today. Enters the meeting room at the
corner, 5th
floor of Techno Building, housing
World2Net (name changed), a telecom based
software company. “Hello”, said Arya, looking at the
colleagues, from all cross functional teams, in the
Network Simulators project, seated in the room.
Srini, the Development Lead, wanted to have a
lighter discussion before the meeting starts. “Guys,
look who we have here—the UM (short for User
Manual)”.
The project team would usually call Arya, the
Documentation Lead as UM, to make fun of him
and documentation. The trend was started when
Arya started raising multiple issues and concerns
with the project team on the management and
execution of documentation tasks in the project. To
the project team, no body reads a user manual, so
documentation work is of least priority—Period.
Dipali, the Testing Lead, joined Srini, “why did you
come, Arya? We have had many such meetings
without your presence. We would send you an
update, like always.” Everybody chuckles. Arya,
knowing that he is at the receiving end, stayed
calm, and said, “I know”. Susant, the Project
Manager, informed others, “I have called him. Mak
checks every cross-functional team’s presence,
especially the doc team”. “Oops, this Mak! What
this guy is made of? Just chokes us.”
Mak, the Product Manager, who recently took
charge of the Network Simulators product, is truly a
business professional, keen on quality delivery.
From the day Mak joined the team, he has raised
many serious concerns about the way the product,
the process, and the project management. In his
observations, the incorrect management of things
internally, is hampering the quality of the released
product.
“Guys, it’s time. Let’s join the bridge. Mak could be
waiting”, said Susant. Lily, the System Engineer and
Technical Architect, dialed the bridge number and
the password. The offshore product team joined
the call with Mak, who works from US. In the
following moments, everybody introduced each
other and had an informal chat. Then Mak started,
“So, this meeting is for C1 of VOLTE. You must know
that having this feature in this release is of high
priority. Many of our customers are waiting to have
it.
Feature backlog
# Feature Priority Release Status
.
.
15 VOLTE
FS: LTE_1101_VOLTE
High 3.1 Schedul
ed
.
.
Many organizations fail to
follow correct agile
guidelines. Thus the project
management is hit, leading
to product quality degrade.
2. 2
World2Net followed agile process (customized
FDD). The Product Manager would find out and
analyze the customer requirements, defines a
feature for every customer requirement. System
Engineers and Technical Architects create Feature
Sheets (FS) for every feature, in consultation with
the Product Manager. The Product Manager
approves a list of features to be release candidates.
The work starts for only these features intended for
the release. Every feature gets developed in
parallel, and goes through a set of six milestones,
from C-3 through C3. Out of these C1 is an
important milestone, which confirms the
commitment of the project team to develop and
deliver the feature.
“Lily, could you run us through the FS please?”, Mak
said. Lily started scrolling down the FS, explaining
the details to the team.
“Ok. So, are we committing to this feature in the
current release? Any concerns, guys?” Arya,
immediately said, “I do.” “The estimate section in
the FS says the documentation effort is included in
the estimate. But, the documentation team is yet to
send an estimate against the feature. And I suggest
to add a Documentation Estimate sub-heading to
capture the documentation estimate exclusively”,
said Arya. From the past email communications,
Mak has been already appreciative of Arya’s efforts
to raise the quality of documentation. He is also
aware of the messed up agile process followed in
the team. Mak, asked Susant to take Arya’s
concerns as actions points and close the C1
milestone, after the action points are resolved.
While closing the meeting Mak mentioned that he
is planning to have a major upgrade in the product
documentation to raise the quality. He will soon
communicate about it.
After a week, Arya receives an email from Mak:
Feature Sheet
Title: LTE_1101_VOLTE
Author: Mak, Lily
Customer requirements:
…
System analysis and plan:
…
Product requirements:
…
Estimate:
…
Release Process
Legend:
U0: Release candidates selected. Start of
project.
C1: Feature is committed.
C2: Feature is developed.
C3: Feature is tested.
U2: System integration tested. Product
release. Project complete.
Note: Prior to C1, every feature go through
C-3 through C0, which are for domain
analysis, approval, solution design, and so on.
U0 U2
C1 C2 C3
F1
F2
F3
F4
If the documentation effort
is not scoped in the project,
the documentation tasks will
miss the project team’s
attention.
3. 3
Minutes later Arya receives another email from
Susant. Like always for any documentation issue:
“LTE User Guide is a 500 page long document. The
effort to redesign and rewrite it from scratch would
take a huge effort. It would need the involvement
of the whole project team. As per the crunch
release schedule, it seems to be an impossible task.
And with the uncommunicative, uncooperative, ill
visional cross-functional teams, this will never be a
smooth ride. God help me!”, thought Arya.
Arya didn’t respond to the email for a day. He
thought a lot. Remembered how voluntarily in
short stints he has been raising the quality of
documentation. He remembered how he has stood
up against the development and testing guys to
close documentation issues. However the scale of
this new task is very different. He can’t take the
responsibility alone. The team has to take it. But the
team is never been interested in documentation.
Eventually they will desert the task. At the release
time the User Guide will be in a meshed up state.
From: Susant
To: Arya
Subject: RE: Need to redesign LTE User
Guide in Release v3.1
FYA.
Regards,
Susant
From: Mak
To: Susant
CC: Lily, Srini, Dipali, Arya, Deepak
Subject: Need to redesign LTE User Guide in
Release v3.1
Dear Susant,
Please look at the following:
Customer feedback (based on recent
survey):
“We couldn’t find a lot of information from
the LTE User Guide. We require it to contain
all basic technical information required to
conduct a test.” - Engineer at Alcatel
Pending documentation defects from
customer:
QC 12111, QC 12345, QC 12456, … Total 32
defects
Product Line Management comments:
“Our customers refer LTE User Guide the
most. We have had many negative
comments from our existing customers. We
need to redesign the document from
scratch.”
We need to address the above raised issues
in the coming release. I.e. in Rel v3.1.
Please do the needful.
Regards,
Mak
Customers are
increasingly demanding
quality docs as their
operation are hit
without it.
Effort for big
documentation works equal
that of a feature. The
project must accommodate
this effort for successful
completion.
4. 4
Arya will become the scapegoat. Something needs
to be done. But, what, and how?
The next day, Arya wrote back:
Hours later Mak had a call with Susant and Arya.
Susant expressed, “the documentation effort is
included in the development efforts of features. We
never had a documentation work as a feature. How
can we release it as a feature? Customers look at
features for added functionality, not documentation
upgrade. Who will write the FS here? Frankly, this is
not the practice we follow in our agile process.”
Arya countered, “An agile project runs to deliver on
FS only. The project resources stays focused on FSs
that are release candidates. You can never deliver
on a large scale work that is not made a release
candidate through the project/process artifacts. The
project resources will stay involved in other release
candidate works and will miss to work on this. Why
you want to take this work as a voluntary work? Are
we doing this for our personal improvement? Who
will own responsibility? How would you budget for
some new resource requirements if needed to
deliver on this work? This is for the project/product.
So map it to the project through its usual artifacts. I
am done with voluntary work. I will work if the
project needs it. And the project needs to show,
that it needs it.”
Arya didn’t wasn’t to miss this golden opportunity.
Because of his voluntary and proactive interest the
documentation management is being stabilized in
the company. If this idea succeeds, he can demand
a FS for each small or large scale documentation
work. This could actually establish documentation
work as a practice in the project. In his mind he
knew that FS is the key. Without a FS, the team
would never commit to the task. Tasks such as
information gathering, document outline
preparation, technical review, etc. would be hit.
The project team knew, one more FS means some
more work. The tight work schedule they go
through, this new task would make it a little worse.
So, they didn’t desire for it. It was evident from their
communiqués. Although they were reluctant to try
this as a new practice for the documentation,
From: Arya
To: Mak
CC: Lily, Srini, Dipali, Susant, Deepak
Subject: RE: Need to redesign LTE User Guide
in Release v3.1
Dear Mak,
It would be nice to redesign the LTE User
Guide from scratch.
Here are my observations/concerns:
As per my initial estimation it would
take us approximately 420 hrs of only
Technical Writing effort.
This effort nearly equals the effort
consumed by an average feature to
develop.
This work needs to be tracked
through the release, with the
milestones and other project artifacts.
The project needs to commit to this
work and needs to adopt this whole
effort.
So, I propose creating a FS for this work, and
making it a release candidate. So that we can
track this using the project/process artifacts.
Regards,
Arya
Project artifacts drive and
track a project. To
establish a work as a
practice, one must make
sure the artifacts reflect
this work.
5. 5
seeing Arya is the only person who could drive this
task, and Mak wouldn’t relent, they kept mum.
Mak seemed upbeat. He needs the new document
to please his existing and new customers. He can’t
take a chance to fail. This new FS approach for
documentation work may enable him to achieve
the goal. Mak subsequently issued a guideline to
the project team to create an FS on the new LTE
User Guide, and cooperate with Arya, as he drives
it.
Arya gets the FS template from Lily and starts
writing it. He has to write it optimally as it would be
reviewed by all, and it will be passed through
milestones.
Soon, Arya calls the team to review the FS and
commit to it in the release. This way, the team
clears the C1 for the FS. Eventually, Arya drives the
work through a regular Document Development
Life Cycle process, and everybody in the project,
members from all cross functional teams
coordinate, cooperate, provide information, write,
and review the document content. Through
frequent minor hiccups the work comes to a
successful finish. The new and refreshed LTE User
Guide is ready. All milestones are cleared. Now, as
the system testing is in progress, Arya, adds the
documentation upgrade work as a “What’s new”
item in the release notes.
As always, after successfully releasing the product,
the team goes to party. After a couple of drinks, the
team is in full merry making mood. Arya, while
dancing himself, sees the whole project team
dancing to the tune of music in coherence. “It is
always a team work, it’s always a project work.
Documents are not outside product.
Documentation team is not outside project team.
Documentation effort is not outside project effort.”,
thinks Arya. The whole team breaks his thoughts
with loud noise, “wohooo…”
By Sudhir Subudhi, Lead Technical Writer, Process
Expert
Email: sudhir.subudhi@outlook.com
Linkedin: in.linkedin.com/in/sudhirsubudhi
Skype: sudhir.subudhi
Twitter: @sudhir43
Release Note
LTE v3.1
What’s new:
…
Enhanced and redesigned LTE User Guide
…
Defect fixes:
…
QC 12111
QC 12345
QC 12456
…
Feature Sheet
Title: LTE User Guide_upgrade
Author: Arya
Customer requirements:
…
Organizational requirements:
…
Analysis and plan:
…
Product requirements:
…
Documentation requirements:
…
Estimate:
…