[Framers] Questions about tech docs in an Agile environment (may be off-topic)

[Pat Christenson]

Good question.

We don't expect the users to read the entire document. There's a mini-TOC on the first page that lists the product sub-sections and new/enhanced features in each. So the expectation is that users will read that and jump to the content that applies to them.

But I'm going to find out if we've ever queried them about how they use release notes and what they would prefer.

Thanks.

Pat

From: Craig, Alison [mailto:acraig at bkultrasound.com]
Sent: Tuesday, March 07, 2017 1:02 PM
To: Pat Christenson <Pat.Christenson at morningstar.com>
Subject: RE: [Framers] Questions about tech docs in an Agile environment (may be off-topic)

Has anyone actually surveyed your market to ask if any of your clientele actually *reads* 30-40 pages of release notes?

My guess is, there's not a chance that most customers even skim them.

Even better than surveying who reads them, survey what your clientele *expect* in a release note.

Alison Craig
Technical Documentation Specialist
BK Ultrasound | acraig at bkultrasound.com<mailto:acraig at bkultrasound.com> | bkultrasound.com<https://urldefense.proofpoint.com/v2/url?u=http-3A__www.bkultrasound.com&d=DwMFAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=T6GFg3V-OYooGTvHqTraHKFeX4ncjwFLstsvhTXIcm4&s=x6KxJvvrOpx9pAveusFaofUQ30setqhE4gd97FID9_I&e=>

From: Framers [mailto:framers-bounces+acraig=bkultrasound.com at lists.frameusers.com] On Behalf Of Pat Christenson
Sent: Tuesday, March 07, 2017 9:09 AM
To: An email list for people using Adobe FrameMaker software.
Subject: Re: [Framers] Questions about tech docs in an Agile environment (may be off-topic)

Thank you all for the information! Naturally, there have been developments here since I asked my question.

One of our product teams that is facing a huge push has designed a very simple Help system. (This was news to me and my management last Friday!) Their plan is for the product managers to write the Help topics, procedures, etc., and I will word-smith it. It's all very simple and their first pass doesn't include features that you would want in a "real" Help system (links, etc.) but it's a start and it's certainly easier than me building from scratch. So we're going to do our part and keep pushing for it to grow into something more robust.

I've had a couple meetings about reducing our gigantic monthly release notes on the other major product. I want to do a list of new and enhanced features with links to the details. I'm also pushing to make the content more focused on people who are familiar with the product. (Right now, we approach every topic as if the user has never seen it before and IMO, that's not the way to write release notes.) The question now is where to store the detailed info and how to re-use it in QuickStart guides, etc.

I'm making some progress--I've been asked to do a mockup of a portion of last month's release notes in my proposed format.

Someone here asked how much is "a lot"? Last month, the release notes for the two major products were 120 pages. It's the largest we've had during my tenure but given the way development is going, that could happen again. (Normally it's been 30-40 pages, which is still too much.)

I'm certainly facing challenges but that's part of why I came to this company. I would like to update this group every now and then on what we're learning and how we're handling it.

Thank you again for your thoughtful input!

Pat

-----Original Message-----
From: Framers [mailto:framers-bounces+pat.christenson=morningstar.com at lists.frameusers.com] On Behalf Of Robert Lauriston
Sent: Thursday, March 02, 2017 1:07 PM
To: framers at lists.frameusers.com<mailto:framers at lists.frameusers.com>
Subject: Re: [Framers] Questions about tech docs in an Agile environment (may be off-topic)

Can you be agile in a heavily regulated industry?

https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ibm.com_developerworks_rational_library_compliant-2Dagile-2Dmedical-2Ddevice_&d=DwICAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=HJebNArynM8pnwN41jSOqsJcPqRSEVwNcO-zKHrbczY&s=XYb8V-DY-dLb2QEGwCI56d7jb1lMPhkRXn8mLrZi05A&e=
_______________________________________________

This message is from the Framers mailing list

Send messages to framers at lists.frameusers.com<mailto:framers at lists.frameusers.com> Visit the list's homepage at https://urldefense.proofpoint.com/v2/url?u=http-3A__www.frameusers.com&d=DwICAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=HJebNArynM8pnwN41jSOqsJcPqRSEVwNcO-zKHrbczY&s=SyWoXBH81_oPwlM-FBI1FCi8wboE-DueuA7ZVfso7kw&e=
Archives located at https://urldefense.proofpoint.com/v2/url?u=http-3A__www.mail-2Darchive.com_framers-2540lists.frameusers.com_&d=DwICAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=HJebNArynM8pnwN41jSOqsJcPqRSEVwNcO-zKHrbczY&s=3KbXh6SDw_feToZSlmsbAmBi6P8kQd1_XfCyKDqN780&e=
Subscribe and unsubscribe at https://urldefense.proofpoint.com/v2/url?u=http-3A__lists.frameusers.com_listinfo.cgi_framers-2Dframeusers.com&d=DwICAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=HJebNArynM8pnwN41jSOqsJcPqRSEVwNcO-zKHrbczY&s=Kjzwbj-5ORz2yjOWGIbFDqRDIoVxIpn10VS-CZjpu6k&e=
Send administrative questions to listadmin at frameusers.com<mailto:listadmin at frameusers.com>
_______________________________________________

This message is from the Framers mailing list

Send messages to framers at lists.frameusers.com<mailto:framers at lists.frameusers.com>
Visit the list's homepage at http://www.frameusers.com<https://urldefense.proofpoint.com/v2/url?u=http-3A__www.frameusers.com&d=DwMFAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=T6GFg3V-OYooGTvHqTraHKFeX4ncjwFLstsvhTXIcm4&s=nw5aiFcpTVt72yW0OQbfb2AyTzMaBlBLAnqtlW6aPNM&e=>
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/<https://urldefense.proofpoint.com/v2/url?u=http-3A__www.mail-2Darchive.com_framers-2540lists.frameusers.com_&d=DwMFAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=T6GFg3V-OYooGTvHqTraHKFeX4ncjwFLstsvhTXIcm4&s=whE1glezIBfVqh-75Cl6L4r0aE1nUyp3LVnpcRtyYjg&e=>
Subscribe and unsubscribe at http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com<https://urldefense.proofpoint.com/v2/url?u=http-3A__lists.frameusers.com_listinfo.cgi_framers-2Dframeusers.com&d=DwMFAg&c=qrd1rYdJNb4QhfvJv5PebOPglYwfSMJ71NR_1HMKptQ&r=XCAkAkKD_C5LA8IHfBffTgJF3-vQqo8LO_6iaUj61_E&m=T6GFg3V-OYooGTvHqTraHKFeX4ncjwFLstsvhTXIcm4&s=jxgU7YQMLCODcicIzxY9fZB16Kv6C_sC1mU5pWFj0IY&e=>
Send administrative questions to listadmin at frameusers.com<mailto:listadmin at frameusers.com>