Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

60%
+1 −0
Q&A How do I approach rewriting an entire user guide in an agile environment?

A user guide is an important result related to your final product and should be treated as such. If the software that is being detailed is in development you you obviously can't know everything tha...

posted 4y ago by Secespitus‭

Answer
#1: Initial revision by user avatar Secespitus‭ · 2020-06-11T22:47:16Z (almost 4 years ago)
A user guide is an important result related to your final product and should be treated as such. If the software that is being detailed is in development you you obviously can't know everything that will happen exactly in advance, but you can treat this like you would treat writing a book: 

- start with a rough outline
- work on each chapter as far as you know
- ask your beta readers / coworkers / users to get feedback 
- rewrite every chapter that needs rewriting

You should plan activities in each sprint that are related to these tasks. This means in the first sprint (or sprints if it's a really big old project) you would work on the outline. In later sprints you would need less time for the "outline" story and more time for the "detail existing chapters" story. Then you will need even less time allocated to the "outline" and still similar amounts of time for "detail existing chapters", plus a bit of "collect feedback". Then you will start to remove the tasks that are related to the outline and to the detailing and replace them with collecting and incorporating feedback. 

In the end you have an evolving document that gets some ideas from the existing documentation and evolves alongside the application. 

The same approach applies to updating an existing user guide for software that isn't rapidly changing at the moment. You take the original documentation as a starting point, look at what changed since the document was last updated, start updating parts and collect feedback on your progress. 

In any case it's important to ask users in one of the first sprints to give you feedback on the current state of documentation. What are they missing? What are they expecting from a user guide? What was good or bad about the old one?

You are in the fortunate situation to have an existing example as orientation, a rough guideline of what needs to be included and probably users with years of experience in using your software and the existing documentation. Make sure that you are talking with your users and not wasting time on stuff that has been changed multiple times by preparing properly in the first sprints and this will be a nice technical writing project.