[Framers] Content Reviews (OT?)

[cuc tu]

Hi All,


I'm not sure if this group is solely interested in FM specific topics or 
generally as a writing community? just a question...


Any suggestions on robust document/content reviews by SME's? I've been using 
Acrobat Shared Reviews hosted on a SharePoint server for several years, but the 
popularity has dropped off quite a bit. Most engineers just don't want to use 
IE or any Adobe product, and even those that do have been upgraded to the DC 
versions and they are not playing well with Acrobat v11 that I use (or maybe 
just not at all?). I'm even having serious 'not responding' issues with my 
tracker and Acrobat in general just hanging... It seems Adobe is the waining 
product, but still has a foothold with no clear competitor, making any kind of 
transition difficult.


Thanks

C
___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] I'm pretty sure the answer is structured content with DITA but I'll ask anyway (LONG)

[Robert Lauriston]

Take a look at Paligo. It gives you structured authoring (DocBook), a
CMS, and reuse in a single package without having to hire a developer
to build a custom system.

On Tue, Jul 26, 2016 at 3:20 PM, Pat Christenson
 wrote:
> I'm the only tech writer in my group. Everyone else is a trainer/presenter 
> (although they do quite a bit of writing).
>
> Our software has numerous components, each on its own release track. At the 
> end of each month, I post extensive release notes on EVERYTHING from the 
> month (written in FrameMaker, distributed as PDF). This is taking a big chunk 
> of time because the preference is for very detailed documentation. 
> Step-by-step, lots of screen shots, and assume the user has never used any of 
> our software before.
>
> This allows the rest of the group to leverage what I write but because it's a 
> monthly release note, all the topics are together in one PDF. It's a pretty 
> safe assumption that none of the users look at it after that month and even 
> if they remember reading about how to use a new feature, they almost 
> certainly don't remember that it was in the February 2016 release notes. Very 
> few people would be willing to open each month's PDF and check the front page 
> for content.
>
> And the cherry on this sundae is all our user guides and help content are 
> very much out-of-date.
>
> I also create a very brief release announcement in HTML that generally 
> describes the new features and directs users to the PDF.
>
>
> My manager has asked me to come up with ideas on how to get more use out of 
> what I'm writing. Some of my ideas are:
>
>
> -  Recognize that these are release notes, not training materials. 
> Assume the reader has a certain level of competence. No more screen shots 
> after almost every step.
>
> -  Update the various product user guides (which would be a 
> gargantuan task, given I'm the only writer) and perhaps pull material from 
> the monthly release notes into each guide as an addendum and appendix.
>
> -  Break the existing release notes in separate docs/books by topic 
> (ad hoc user guide). In the monthly release announcement, link to those.
>
> -  Make a master book of release notes with a TOC and maybe even an 
> index (Lord, where would I find the time?). Even if it's still organized by 
> month, the user would have a way to skim for content.
>
> In the long run, we probably need to get away from the idea of release notes 
> in one document (or in a document at all). We should probably be chunking and 
> tagging material, using a CMS, and single-source this into Help, release 
> notes, etc. But we are a small group with a great deal of legacy 
> documentation. I've been here 6 months (there was no tech writer before-each 
> product team "wrote" its own release notes). Everyone loves that the notes 
> are now well-written and comprehensive, and look polished, but my manager and 
> I both feel that I'm building up more documentation that isn't flexible.
>
> I hope this group may have some ideas. I can't stress enough that right now, 
> we need short-term solutions.
>
> All ideas and suggestions will be greatly appreciated.
___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

[Framers] I'm pretty sure the answer is structured content with DITA but I'll ask anyway (LONG)

[Pat Christenson]

I'm the only tech writer in my group. Everyone else is a trainer/presenter 
(although they do quite a bit of writing).

Our software has numerous components, each on its own release track. At the end 
of each month, I post extensive release notes on EVERYTHING from the month 
(written in FrameMaker, distributed as PDF). This is taking a big chunk of time 
because the preference is for very detailed documentation. Step-by-step, lots 
of screen shots, and assume the user has never used any of our software before.

This allows the rest of the group to leverage what I write but because it's a 
monthly release note, all the topics are together in one PDF. It's a pretty 
safe assumption that none of the users look at it after that month and even if 
they remember reading about how to use a new feature, they almost certainly 
don't remember that it was in the February 2016 release notes. Very few people 
would be willing to open each month's PDF and check the front page for content.

And the cherry on this sundae is all our user guides and help content are very 
much out-of-date.

I also create a very brief release announcement in HTML that generally 
describes the new features and directs users to the PDF.


My manager has asked me to come up with ideas on how to get more use out of 
what I'm writing. Some of my ideas are:


-  Recognize that these are release notes, not training materials. 
Assume the reader has a certain level of competence. No more screen shots after 
almost every step.

-  Update the various product user guides (which would be a gargantuan 
task, given I'm the only writer) and perhaps pull material from the monthly 
release notes into each guide as an addendum and appendix.

-  Break the existing release notes in separate docs/books by topic (ad 
hoc user guide). In the monthly release announcement, link to those.

-  Make a master book of release notes with a TOC and maybe even an 
index (Lord, where would I find the time?). Even if it's still organized by 
month, the user would have a way to skim for content.

In the long run, we probably need to get away from the idea of release notes in 
one document (or in a document at all). We should probably be chunking and 
tagging material, using a CMS, and single-source this into Help, release notes, 
etc. But we are a small group with a great deal of legacy documentation. I've 
been here 6 months (there was no tech writer before-each product team "wrote" 
its own release notes). Everyone loves that the notes are now well-written and 
comprehensive, and look polished, but my manager and I both feel that I'm 
building up more documentation that isn't flexible.

I hope this group may have some ideas. I can't stress enough that right now, we 
need short-term solutions.

All ideas and suggestions will be greatly appreciated.

Explore complimentary learning 
opportunities

Pat Christenson
Senior Technical Writer, Client Education
Morningstar, Inc.
pat.christen...@morningstar.com

___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] OTS DITA and CMS

[Robert Lauriston]

Flare would make it a lot easier to manage those projects. Its
FrameMaker import is quite good. Docs are defined by graphical TOC
trees of topic file icons. You can swap topics in or out quickly and
easily to match whatever actually ships.

What revision control system are the developers using? You could put
the docs in the codeline along with the features and generate the docs
as part of the build, automatically ensuring that the docs match the
release. I think that accounts for the popularity of Markdown /
AsciiDoc / reStructuredText plus Jekyll / Hugo / whatever despite
their relative crudeness compared with popular authoring toolchains.

Personally I would argue for more sophisticated release management
instead. "Oh, we shipped? Everybody scramble!" is a pretty good sign
you're not following best practices.

On Tue, Jul 26, 2016 at 12:17 PM, cuc tu  wrote:
> Hello All,
>
>
> I'm looking for a quick and easy transition to a more modern workflow to help 
> keep up with
>
> software development. I've currently only authored in unstructured Frame 
> under a book
>
> paradigm, and am finding it impossible to track development. Basically, we 
> have two writers
>
> to support ~30 developers. The SW group has moved to an agile scrum process 
> and create
>
> software features in modular form. Then they are checked into the SW pool and 
> tested by
>
> another team who then publishes the FW releases to the Web team. The testing 
> takes about 1
>
> to 2 weeks and some features may not get released. Also, we do not really 
> know when the SW
>
> is released until it goes live (much of the process is automated and 
> decisions happen
>
> overnight). Dev cycles are three weeks and the software is usually not 
> available until it
>
> is checked in for testing since there are many dependencies.
>
>
> I'd like to find a way to have content more modular and easy to snap-in/out 
> like the
>
> software folks can switch on/off software features. I've thought of trying 
> this with
>
> conditional text, but I think the complexity and granularity of what needs to 
> be controlled
>
> is too high. I'd also like for the writing resources to be more agile so they 
> can work on
>
> any document piece as needed. Right now, we move around and track "book" 
> packages and
>
> publish PDF books with incrementing revisions.
>
>
> Any suggestions on how to proceed or where to look for some ideas?
___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] OTS DITA and CMS

[john . x . posada]

Have you tried Book Include/Exclude?

John X Posada
AVP | Global Risk Analytics | HSBC North America Holdings Inc
330 Madison Ave., NY NY

 __ 





 Phone  
 Int: 212-525-5483 Ext: 646-735-1857
 Fax
 Conference Bridge - 877-304-0052, Code 
 74809254   
 Email  
 john.x.pos...@us.hsbc.com  

 __ 
 Protect our environment - please only print this   
 if you have to!






From:   cuc tu 
To: "framers@lists.frameusers.com" 
Date:   07/26/2016 03:18 PM
Subject:[Framers] OTS DITA and CMS
Sent by:"Framers"   



Hello All,


I'm looking for a quick and easy transition to a more modern workflow to
help keep up with

software development. I've currently only authored in unstructured Frame
under a book

paradigm, and am finding it impossible to track development. Basically, we
have two writers

to support ~30 developers. The SW group has moved to an agile scrum process
and create

software features in modular form. Then they are checked into the SW pool
and tested by

another team who then publishes the FW releases to the Web team. The
testing takes about 1

to 2 weeks and some features may not get released. Also, we do not really
know when the SW

is released until it goes live (much of the process is automated and
decisions happen

overnight). Dev cycles are three weeks and the software is usually not
available until it

is checked in for testing since there are many dependencies.


I'd like to find a way to have content more modular and easy to snap-in/out
like the

software folks can switch on/off software features. I've thought of trying
this with

conditional text, but I think the complexity and granularity of what needs
to be controlled

is too high. I'd also like for the writing resources to be more agile so
they can work on

any document piece as needed. Right now, we move around and track "book"
packages and

publish PDF books with incrementing revisions.


Any suggestions on how to proceed or where to look for some ideas?


Thanks,

C

___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at
http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com


**
This message originated from the Internet. Its originator may or may not be
who they claim to be and the information contained in the message and any
attachments may or may not be accurate.
**




-
**
This E-mail is confidential. It may also be legally privileged. If
you are not the addressee you may not copy, forward, disclose or
use any part of it. If you have received this message in error,
please delete it and all copies from your system and notify the
sender immediately by return E-mail.

Internet communications cannot be guaranteed to be timely, secure,
error or virus-free. The sender does not accept liability for any
errors or omissions.
**
SAVE PAPER - THINK BEFORE YOU PRINT!
___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

[Framers] OTS DITA and CMS

[cuc tu]

Hello All,


I'm looking for a quick and easy transition to a more modern workflow to help 
keep up with

software development. I've currently only authored in unstructured Frame under 
a book

paradigm, and am finding it impossible to track development. Basically, we have 
two writers

to support ~30 developers. The SW group has moved to an agile scrum process and 
create

software features in modular form. Then they are checked into the SW pool and 
tested by

another team who then publishes the FW releases to the Web team. The testing 
takes about 1

to 2 weeks and some features may not get released. Also, we do not really know 
when the SW

is released until it goes live (much of the process is automated and decisions 
happen

overnight). Dev cycles are three weeks and the software is usually not 
available until it

is checked in for testing since there are many dependencies.


I'd like to find a way to have content more modular and easy to snap-in/out 
like the

software folks can switch on/off software features. I've thought of trying this 
with

conditional text, but I think the complexity and granularity of what needs to 
be controlled

is too high. I'd also like for the writing resources to be more agile so they 
can work on

any document piece as needed. Right now, we move around and track "book" 
packages and

publish PDF books with incrementing revisions.


Any suggestions on how to proceed or where to look for some ideas?


Thanks,

C

___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

[Framers] ANN: (REMINDER) TC Summer Camp!

[Scott Prentice]

Just a reminder that TC Summer camp is this Saturday, July 30, in 
Fairfax, VA at George Mason University!


If you're in a reasonable distance to Fairfax, VA and interested in 
having a great day of techcomm learning, sharing, and networking .. 
please join us!


...scott


 Forwarded Message 

You may have heard of TC Camp, the techcomm unconference, held for the 
past 4 years in the San Francisco bay area .. well, we are taking it on 
the road and holding a TC Summer Camp on Saturday, July 30 in the 
Washington DC area! If you're in the area or within an easy drive (or 
train) to Fairfax, VA, you might consider joining us!


If you're unfamiliar with the term "unconference," it's basically a 
conference where the topics/sessions are defined by the attendees on the 
day of the event. There are no presenters, but rather you gather at a 
table with other like-minded people who want to discuss the selected 
topic. We start the day with optional workshops run by techcomm 
luminaries, then have the unconference in the afternoon.


TC Camp is free (mostly), and is a great day of learning, sharing, and 
networking for techcomm professionals. You can learn more about camp at 
our website ..


http://www.tccamp.org

For a quick overview of things, watch some interviews and videos from 
past years ..


http://youtube.tccamp.org

Feel free to ask me if you have specific questions!  :-)

If you provide services or products to the techcomm world, perhaps you'd 
be interested in sponsoring! Because TC Camp is free (mostly) for 
attendees, we rely on our generous sponsors to make it all happen. 
Please contact me for details.


Cheers!
...scott



___

This message is from the Framers mailing list

Send messages to framers@lists.frameusers.com
Visit the list's homepage at  http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com