Agile and collaborative documentation production - the key to achieving user satisfaction
•Als PPTX, PDF herunterladen•
1 gefällt mir•363 views
How can agile methods and collaborative content building improve how we do documentation for software users? The role of technical writers is evolving to being architects or a content stratgey, see why.
Empfohlen
Empfohlen
Weitere ähnliche Inhalte
Ähnlich wie Agile and collaborative documentation production - the key to achieving user satisfaction
Ähnlich wie Agile and collaborative documentation production - the key to achieving user satisfaction (20)
Kürzlich hochgeladen
Kürzlich hochgeladen (20)
Agile and collaborative documentation production - the key to achieving user satisfaction
- 1. Agile and collaborative production - a key to achieving user satisfaction? Andy McDonald, edc product manager
- 2. State of the art Technology Traitement de texte SGML Internet XML DITA Norms Media Training
- 3. Use case User documentation for a multisipliniary geoscience software platform -4 years, after restarting from scratch -- contextual documentation on >1000 UI elements -- >1600 pages added on top of that -- 2TW + experts + support team Planned and managed in agile mode
- 4. Use case Full coverage is not enough What users are we dealing with, and what are the issues ? New users Expert users - Getting up and running when training is too hard to organize - How can we provide information on what they don’t know ?
- 5. Use case What is the client asking for? • taxonomy based search • participation • annotation, comments & contributions (in their products) • usage statitstics • UI ergonomics & terminology • new forms animation, video, e-learning
- 6. Market Study How software editors deal with documentattion Panel of editors • startups / intermediairy size • french market/ international • classical business model / SaaS • installed products/ web based • opens source / proprietary
- 7. Market Study Documentation is a liability • stuck in a design model where obscelescence predmoninates Form and process stuck in the 1990’s • creation unsychronized with development (even in agility) • it’s not connected, hardly multimedia or interactive and often out of date
- 8. Market Study Unable to reinvent the model • mnimum service only • or complete • even if they are « innovators » • they can’t image anything different, interactive, innovative Document is a cost centre, and far from an added value
- 9. Software Editors How to motivate them ? • identify added value • concentrate on user satisfaction • propose a better production model
- 10. Software Editors What can we propose • they/ we take over • better explain and agree on what we add • be a part of the development process
- 11. Software Editors And Writers What can we suggest ? • they / we manage a content strategy • build documentation with agile methods • build from the ground up • implement collaboration
- 12. Content strategy Objectives Audience Distribution channels Contents structure Source identification Validation mechanism
- 13. Incremental building Bottom-up production • start with the UI • add connex subject matter • comment, contribute • validate • publish
- 14. Collaborative work processes Who collaborates & how? • developers & TW • support & TW • experts & TW • product owners & TW
- 15. Agility & content strategy + Content strategy can fit into agile methods
- 16. Agility & content strategy +An overview is designed with the product owner
- 17. Agility & content strategy +Target audience is defined when defining the requirements
- 18. Agility & content strategy + Publishing cgannels Are defined in plannifaction
- 19. Agility & content strategy + Content building An iterative phase alongside project dev in sprints depth of contextual doc on UI bricks defined with developers - connexe doc depending on objectives - procedures with experts - FAQ & Howtos (with support - tutorials with training
- 20. Agility & content strategy + Sources are also human - PO > concepts - PO & experts > procedures - supportknows user needs - trainersknow what tutorials they need
- 21. Agility & content strategy + Tests & validation during development Feedback is continuous - capture user experince - improvement cycle
- 22. TW implementing change TW beyond writing • architect - structure & contents • responsability - editorial cycle • abritrator - production cycle
Hinweis der Redaktion
- Good morning, I’m the easydoccontents product manager at TECH’advantage in the Paris area. I’ve been working since the late 1980’s in software documentation, especially in the oil and gas industry, for CGG, IFP and Total, where we documentation huge multi-displinary software platforms. At TECH’advantage we’re transforming all this experience and know-how into a new software product for building documentation.
- Before we get into the heart of the subject, let’s just agree on the state of our art today. A lot of us have seen technology, norms and media evolution especially since the internet explosion. Today there is a lot of hype around social networking, and we’re all involved in that. We have all training ine one way or another, and experince that has led us to where we are. We spend a lot of time concentrated on things like DITA, pondering about what is the best way to get a message across, and for such we all have our own preferences. We’re convinced we know how to do a good job. Let’s have a look at one example.
- One example of what we’re doing today: With Total in the SW of France, we’ve been managing the documentation of their geoscience software tools for the past 4 years. They tried a lot of methods for documenting before us and when we stared with them, we basically threw most of it out. Over the past for years, we concentrated on contextual documentation, starting from the UI and building on top of that with, procedures, theory, faqs. We have two TW working there, but they’re not alone : over 30 developers, a support team of 6, 20 experts and 3 client representatives contributing to the documentation. The entire maintenance and the documentation is manged using agile methods. I’ll be talking about this just after.
- Until end 2014, the priority was quantity and coverage, try to deal as much and the product as possible. Since the beginning of 2015, the client’s demands have evolved, especially since the basic elements are now covered. Now the focus is on quality and expertise, especially around new releases. Two kinds of users need to catered for… For new users, the requirement is for them to get started and continue using the products. For experts, a lot of them have been using the software for ages. They know what they need to do. They key issue is helping them do it better. How can we deal with these two issues at the same time? We can’t really. For new users, an obvious response is training, but training costs a fortune and lasts almost a week. It costs a fortune because of travel expenses and time costs in which they are identified as non productive. We probably all know about media that can help such as tutorials, webinars etc. So we can easily build a strategy… For experts, how can we detect what they need and tne provide it. This is a hard one. Total has a service for methodology, but even they don’t know everything. They cover at least ten fields all the way from data acquisition, through interpretation, conversion, well management, then reservoir detection, oil & gas production and then asset management. Don’t worry, we find it complex too.
- Our client has more managerial requirements. Our TW are often the first testers, so their angle on terminology and ergonmics is a real added value, and often doing these two correctly avoids having to produce basic documentation. Usage statistics are envisaged for managing documentation – for instance, review or remove what is not read. They want to get more involved but in front of their own product and not out of context, by adding comments and providing added contributions. As far as the documentation we produce is concerned, a proper search mechanism is required, but it can’t be a standrd one which would produce even greater frustration. The last demand is one of the easiest to deal with – we use other media, but the content has to be expert!
- Let’s have a look at a market study we carried out end of 2105 – early 2016. The study adressed a large panel of more or less small businesses who are software editors. We were trying to find out how they deal with software documentation in order to detect our product value in the market.
- Documentation is a liability for software editors The first conclusion is quite severe. In a lot of cases, software documentation is still a reuiremnt of their leads and clients. Documentation is however considered a liability – they remain predominated by the rapid obscelescence of information withour knowing how to deal with it. Form and process stuck in the 1990’s When they actually do some documentation, their methods of design and update have nothing in common with their development methods. Thhis is even more remarkable for those using agile methods – when time to market decreases, for instance with rapid delivery, they often exclude documentation. When they do documentation it is done in aprallel to the product in question. This documentation is static, often PDF only, and rapidly out of date. This is also a major problem for internationally distributed and localized software.
- They don’t know how to reinvent the model Most of the editors interviewed just admit this situation and seem happy with a strict minimum. Some are even proud of having no documentation at all. What’s striking is that, even if software innovation is a core preoccupation, they are incapable or imagining documentation in any form other than the 90s. They can’t automatically imagine a documentation which is interactive, reactive, integrated into their processes. Documentation is a cost centre with no vision on ROI. Documentation is not seen as an added value.
- What will motivate software editors? Our experience, our technology and our know-how has little effect on software editors we interviewed. This may be a cultural trend of course. But I like to think it’s isn’t just that. Given the conclusions of the study, it’s a serious enough situation to wonder if we’re selling our business correctly. Talking about all our internal issues and preoccupations, norms, writing styles, DITA, minimalism, structure is more likely to frighten them off. None of these are a business proposition, which is what they need to see and which they will buy into. We have identified three angles for getting them back onboard: Identify added value that they can understand to their product/business proposal. Orient all work towards user satisfaction and involvement. Propose a production model they can adhere to, that fits into their own production model. Added value This is a hard one to identify. A series of key arguments can come into play: Better quality of the UI through developer – TW cooperation. Lesser support usage due to better product information and use cases. Documentation adapted to real needs and capable of being multi channel. Lower overall mainteance costs and the ability to easily stay up to date. Easier internationalization. User satisfaction This is what the whole game is about: satifsfying users and improving the whole user experience, and beyond that, encouraging user participation. A better production model Our methods of producing documentation have to fit theirs, whether it be the older V-cycle or agile. Software editors have to being involved at each stage and allowed to make key decisions easier.
- What can we propose as a change for software editors? One of the key factors of success is any new documentation model for software is getting the editors themselves involved in the whole process. Either they take control of their are involved in aprocess we manage for them. This is why we will talk later about content strategy as a basid for managing this. We need to better explain what segments of content we can add, why and how. Part of defining a strategy is also agree on what needs to be done with editors who are then wholly implicated. As I see it, designing documentation (and other information) around software has to be a part of the product development cycle. There are two type: the classical V-cycle which is over longer periods of time, and agile methods which are geared to rapid delivery, stage by stage. Not all editors are agile, so we can’t just cater for that.
- How can we adapt and propose change in the process? The are four major evolutions we can propose: Manage the documentation project using a content strategy guideline. This is done by the software editor or by us, but it all has to be clarified. It’s a form of contract. Use agile methods to build the documentation, even if the software editor isn’t using this himself. Build content from the ground up by moving as much content inline as possible. The entry point for documentation is in the software. Implement as much collaborative content building as possible.
- What do we mean by content strategy? As far as we see it, a content strategy is composed for 6 major elements. Once decided, it become a governing guideline. As such it can vary from product to product and from version to version. Once major advantage of this is that the scope can be limited to something achievable. Define the overall objectives This is about the big picture, but it has to be achievable. It’s the overall scope of a project, it’s ambitions. While this could be vast, the idea is to limit it so that delivery with the product version is tangible. Define the target audience Decide on distribution channels Define the content structure elements to be used Identify sources and source materials Define the validation mechanism
- Incremental Building This is all about writing the documentation in the right phase. As far as we see it, providing an entry point to the documentation in the UI is essential. To succeed in this, developers and writers have to work together. Developers need writers to help them with the UI ergonomics and writers listen to what the developers have done. The result is essential, minimalist contextual documentation. In some cases this documentation may even be absent if proper terminology and ergonomics is dealt with in the UI. The user has needs that go beyond the first entry level. We consider this to be connex, but not in the sens of making it less important. We have to consider that readers don’t want tons of contents in one session. We add these subjects through suggested links. Connex subject types depend on the software and often will include explanations on doing a job better, dealing with potential issues, learning technical stuff. This type of content is not written alone. Support teams, trainers and experts have to contribute, even if the technical writer has to re-write it. Commenting and contributing more is a key step. It’s part of a longer validation process. Tech writers can’t provide all content alone. Validation is the job of product managers/owners. Some editors may not need it, but in team work it gives a good idea on advancement of the work load. Publishing is more and more multi-channel. Multi-channel doesn’t just mean different media types. The first chanel is in the the software with a structure that promotes incremental reading. The second major channel is to a support portal when users can provide feedback and support teams can request or create more content. A third channel is a documentation portal itself.
- Collaborative production and writing Sevral participants in software product devleopment have a key role to play in making the user documentation better. Developers and TWs work together to improve the UI and write the basis contextual documentation set where it is needed. Support teams work with TWs because they know the clients and probably can anticipate what questions will emerge. Experts have a lot of technical input to add.
- Agility and a content strategy A content strategy needs to be defined to work with software developement, so that all parties agree on what has to be done and have a roadmap for getting it done. It can easily fit into agile development.
- Overview – the big picture: What are the overall objectives? What’s the scope of the documentation? What are the project constraints? What reference material exists? What are the priorities? This allows everbody to agree.
- Define the target audience What types of users are to be dealt with? What are the first ambitions to be dealt with?
- Decide which export channels need to be dealt with Contextual in line documentation – what depth? Where is the boundary to be placed with support? Does any content overlap with training?
- Deal with the content structure Scope and depth of bricks to be covered Connexe subjects depending on the product FAQs, Howtos Procedures Concepts
- Establish which sources can be used: Existing materials Experts available Product stakeholders
- Manage validation and feedback Validators Feedback management
- Role of technical writers beyond writing From what we can see, the role of technical writers is evolving to include: Content strategist in collaboration with product key actors Architect of an information structure with varied needs and objectives Reponsability in the entire editorial cycle, stimulating, sollicition, re-writing Abritrator in the production cycle with developers and product managers, support teams, helping them all decide.