Real-time collaborating without Contributor?

[sdcinvan]

Forgive me if I already posted a topic on this subject... It seems familiar but I cannot find a related post.

I am wondering if I am in a unique position, where MadCap Contributor isn't a practical tool to collaborate with SMEs and stakeholders?

The reasons?
a) I am working with many different SMEs, rather then a few of the same SMEs for every project. Sometimes the SME will only be responsible for revealing one chapter (or less), one time only. It isn't practical to request that each SME download and install MadCap Contributor the one time collaboration request.
b) Even more of a show-stopper... many of my SMEs are engineers that only work on Linus based systems.
c) Some of my Stakeholders are MAC users (sans Windows emulation). Contributor is a Windows only product.

So, I needed to find an alternate way to collaborate.

Enter Google Docs...
If I build my draft document using Google Docs, any number of people can review and edit (or comment) content live and simultaneously. It works great but their is a few caveats:
a) The content must be manually copied into Flare.
b) Once edits take place in Flare, the Google docs draft becomes permanently out-of-date.
At this point, I need to switch to a new collaboration tool...

Enter Crocodoc...
The value to Crocodoc is that I can publish Flare content and reviewers can comment and annotate directly on Flare's PDF output. But there are a few caveats:
a) Any updates must be uploaded as a new file. Annotations and comments are not carried over.
b) Because of (a), it is only practical to upload a new Crocodoc file when there are significant changes.

The main point of this post?

The ultimate ideal solution is that MadCap build a free (or very inexpensive) online/system agnostic version of Contributor.

Failing that, I am looking into building a parser that would allow merging new MadCap content with Google Docs.... one-way (always Flare to GDocs). That way, reviewers will always see the latest version of the docs (that they can comment within) from Google Docs.

Does this appeal to anyone? Or do you have a better idea? If so, I look forward to your share.

Best regards,
Shawn

[rob hollinger]

Excellent idea Shawn.

I have a few questions that could help us answer some of our own questions when discussing SAAS.

Would you prefer to host your own server or use MadCap Servers?
What kind of security would you require?
There would need to be some kind of notification system to authors would know then files are completed?

These are some of the questions we have had when talking about this very subject. Thanks for any additional information provided.

[sdcinvan]

Would you prefer to host your own server or use MadCap Servers?

Just a few quick replies... you got me excited by your interest.

Everyone has different requirements so ideally, you should offer both a SAAS and self-hosted solution.

In some situations, self-hosted might be the only option, no matter how much security MadCap promises. i.e. Many government operations are 100% internal with 0 access to the public Internet. In our case, we are building documentation in a highly competitive field. Our documents only go to our POC customers.

What kind of security would you require?

Security is always important in every situation. At a minimum, individual authorization... with one to three levels of authorization
i.e.
author - full access with direct to Flare content merging (this could be offered as a premium account - prices set by number of author accounts required)
- essentially, all the practical features of the paid version of Contributor
reviewer/editor - partial editing capabilities and full commenting but cannot import/export to Flare
commenter - can only comment, read and reply to other comments, copy and paste comments. (I suggest this be a free or nearly free version - make it 'easy' for entry level to use this)
- similar to the currently free version of Contributor
- allow for individual commenter profiles but perhaps limit the number of profiles to 10? (that is pretty important zero cost feature)

There would need to be some kind of notification system to authors would know then files are completed?

Yes, notification to one or more authors assigned would be very useful.

Other thoughts:
- Invite reviewer directly from within the tool by way of email address and short 'canned?' message.
- Perhaps offer extended security (i.e. HTTPS 256bit) for a small additional cost? Otherwise offer reasonable security for low cost to free.
- Relatively important for the interface to be system agnostic... HTML5? So that it is even mobile capable.
- Live chat
- A mini open forum area where reviewers can freely discuss general comments about the documentation.

If MadCap can offer something close to this, you will absolutely dominate the documentation tool world! AFAIK, no one else offers anything remotely similar.

dag gommit, I want to work for you guys to help develop this!

[ghillerson]

I'm in the same position: working for a software company that is all Linux/MacOS, which makes review/contributor issues really difficult with Flare. We love Flare's single sourcing, but the PC-only restriction is very limiting, and I may be forced to change tools in the future because of that. Our engineers, tech support, and marketing people are all using Google Docs, which makes importing and collaborating awkward, if not difficult. I may be able to convince one person to run Flare under VMWare, but not the team, and that's bad news.

Come on MadCap! Let's have Contributor-like functionality for MacOS/Linux users. Just being able to add comments/annotations would be a major step forward.

gary

[MageWriter]

Try to use whatever code review tool your developers already use. That way they don't have to learn anything new and it's something you already have on your network.

For us, it's Fisheye. It's integrated with Jira so any comments in the review get seen by all review participants and are also recorded in Jira. (You could also use github.) My source is in SVN and it's easy for me to create and manage the review. I can say more if you already have Fisheye.

The downside is that Flare HTML source is very hard to read. I also link to the formatted HTML which displays from the SVN repo.

Speaking of github, it already has a built-in fork/pull/merge system. If your developers use it, consider that route.

[MageWriter]

Contributor will never fly. It's a 100MB+ application that requires C++ runtimes which only MS shops will use. It's a non-starter and IMHO a poor choice.

[RamonS]

Contributor will never fly. It's a 100MB+ application that requires C++ runtimes which only MS shops will use. It's a non-starter and IMHO a poor choice.

I agree, a browser based app would be more suitable for even the casual contributor. A browser based app comes with its own issues (probably will work fine on any browser except for IE), but when done right it can work from any device.

[chunkee]

I am still using Feedback Server for content evaluation and sign off from SMEs. It provides an alert and can be utilized immediately. Use the you can place comments in the feedback to annotate that is has been reviewed. This is on my dev server. I use Pulse on the production server, however, it has not been well received due to its klunky functionality and lack of features, especially AD integration or SAML SSO functionality.

-John C

[sdcinvan]

Contributor will never fly. It's a 100MB+ application that requires C++ runtimes which only MS shops will use. It's a non-starter and IMHO a poor choice.

I agree, a browser based app would be more suitable for even the casual contributor. A browser based app comes with its own issues (probably will work fine on any browser except for IE), but when done right it can work from any device.

I've been on MadCap's case about this since I joined the Flare family back in August.

Another use case for a web-based contributor-style tool is when a writer works with many different subject matter experts for each new project. It is quite unreasonable to ask a SME to install Contributor when they may be a SME for just a few days. Also, in my experience, many of the SMEs that I have worked with either:
a) Don't have software install rights on their computers (and it is an ordeal to get new/temporary software installed)
b) Do not have Windows based computers

So... despite owning Contributor (as part of the MadPak purchase), the tool is utterly useless to me.

My workflow work-around is:
1) Build draft documents in Google Docs
Advantages:
- No restrictions on editing or commenting (I can invite anyone in to review and comment and/or edit content).
- Real-time content review and editing (with automatic email notifications).
Caveats:
- SMEs and stakeholders cannot see how the documentation will appear (b/c formatting in Docs is poorly implemented).
- Requires an additional and tedious step of copying/pasting into Flare after draft work is complete.
- Forever out-of-sync once I begin fine-tuning in Flare (unless I copy back into Docs).

2) Publish Flare content to review in Crocodoc (https://personal.crocodoc.com)
Advantages:
- No restrictions on commenting (I can invite anyone in to review and add comments and/or annotations).
- Near real-time content commenting (with automatic email notifications).
Caveats:
- Conversion of Flare PDF output to Crocodoc's HTML5 viewing format isn't perfect (the occasional formatting error may be misinterpreted as a documentation error)
- Relatively 'long' process to publish in Flare (as PDF) and then upload to Crocodoc (Crocodoc doesn't support document replacement so comments don't follow to a doc update)
It isn't practical to update with new Flare content until there are significant updates.
- Comments must be manually applied to the Flare source.

In short, it works but it certainly isn't ideal!

[sdcinvan]

I am still using Feedback Server for content evaluation and sign off from SMEs. It provides an alert and can be utilized immediately. Use the you can place comments in the feedback to annotate that is has been reviewed. This is on my dev server. I use Pulse on the production server, however, it has not been well received due to its klunky functionality and lack of features, especially AD integration or SAML SSO functionality.

-John C

Hello John,

Are you referring to this service... http://feedbackserver.com/ ?

How does it compare to my own workflow, as outlined in my last post? Does it eliminate any of the steps in my workflow? A better alternative to Google docs and Crocodoc?

[RamonS]

Sorry to butt in here, but I think the talk is about MadCap feedback server. It is a service that allows for users to add comments to topics. While intended for end users 'abusing' it for SME contribution / signoff is a clever idea.
Here is a blip about Feedback Server http://www.madcapsoftware.com/blog/2008 ... lp-server/
Appears to have been absorbed into Pulse now.

[sdcinvan]

Sorry to butt in here, but I think the talk is about MadCap feedback server. It is a service that allows for users to add comments to topics. While intended for end users 'abusing' it for SME contribution / signoff is a clever idea.
Here is a blip about Feedback Server http://www.madcapsoftware.com/blog/2008 ... lp-server/
Appears to have been absorbed into Pulse now.

Thank you for the clarification.

At this stage, I can't justify the cost of implementing Pulse... I really wish there was a 'lite' version that simply accommodated one author, many temporary SMEs and allowed review plus commenting and sign-off.

[RamonS]

When I was involved with docs as SME I used PDFs and notes and annotations in them. Yes, it is not as seamlessly as it could be because the tech writer needs to make the changes manually, but it was a simple, inexpensive, easily traceable process. What it lacked was any kind of progress indication. As SME I was very interested in having specific items be described and spelled out clearly because they are important. I had to keep track of those changes manually as well and nudge the tech writer multiple times to put the changes in.
I think a tool that can display the current version of a topic and allows for marking a spot or roping in an entire text area will be fine. The spot / area is then tied to the requested change/addition/removal. Each of the requests gets a unique ID and is marked with date, time, requester, and the TW making the change with some simple status (requested, in process, done, rejected/retracted, needs clarification) and an assigned owner based on state. What might be beneficial as well is an attachment feature for screen shots, images, or existing documentation that the SME wants to have included. Those attachments would be part of a request.
What I wouldn't necessarily see a need for in such a tool is any formatting that goes beyond the styles presented in the project's style sheet. Even an off the shelf RTF edit control might be good enough.
Any such tool should be a simple install that can either hook into IIS, Apache, or if desired fire up its own web server (there are plenty of open source or at least freeware web servers) and have a choice of using an existing SQL server (MSSQL, MySQL/MariaDB) or a local database engine to keep track of things. My point here is that deployment should be easy and not require anyone to necessarily turn on and configure a specific web or SQL server. Click a button, answer a few questions, and start using it five minutes later.

Of course, there will be requests right after release to integrate with a gazillion of things because folks want to use TFS, SharePoint, Jira, Oracle, SalesForce, SalesLogix, SVN, CVS, Git, VSS, PostGres, Lotus, Access, Excel, Outlook, Facebook, Twitter, MySpace, Instagram, Snapchat, or what else is floating around with that tool. Maybe a plugin engine might help here. Since the goal is simplicity and ease of deployment I'm not sure that this would help the cause.

@MadCap - sounds like a nice project for a summer intern. Seriously, putting such a web app together isn't particularly difficult. The biggest challenge might be the state/workflow engine, but even that concept can be borrowed from other places.