Madcap Flare or Sphinx

[sconnelly]

Hello all,

I just started a job where I must make a decision about the documentation tool to use. My primary experience is with Word, Framemaker, and InDesign. There is a little bit of a push for Sphinx... not because it is free but because the content I produce is editable by other collaborators in plain text, plus it fits well into our git source control system.

I am looking for some advice...I realize that I might get a biased opinion and that is fine, as long as it is factual.

The primary criteria for a documentation tool are:

Essentially, I am looking for the following attributes:
- Ability for others to edit content WITHOUT requiring any special tools (many of the reviewers/contributors use Linux).
BTW, I use Windows for documentation.

- Plays well with git (gitorious) source control.

- Single source documentation that will output/accommodate (with little or no edits) to
the following formats:
XML/HTML5/WIKI publishing, and PDF

- In terms of content control, the product should offer the same (or better) flexibility as Adobe
InDesign or Framemaker.


If Madcap Flare is the right product, what is the learning curve like (considering my experience)? Is there online (video/interactive) training available? I will not have time to travel for classroom training.

Thank you for your much appreciate help!
Shawn

[NorthEast]

If the main consideration is that you want others to freely contribute and edit the content, without installing tools and across multiple platforms, then it essentially sounds like you need a wiki.

Flare wouldn't work for this type of scenario; multiple authors using Flare would all need to edit the content using Flare, and after editing the outputs would need to be built and published.
I'm not familiar with Sphinx, but at first glance that doesn't appear to be a wiki either.

[sconnelly]

If the main consideration is that you want others to freely contribute and edit the content, without installing tools and across multiple platforms, then it essentially sounds like you need a wiki.

Flare wouldn't work for this type of scenario; multiple authors using Flare would all need to edit the content using Flare, and after editing the outputs would need to be built and published.
I'm not familiar with Sphinx, but at first glance that doesn't appear to be a wiki either.

Thanks for your reply.

No, a wiki is not a suitable way to create documentation, especially full sized manuals. The tool I settle on, however, must be able to output a help file, wiki, or PDF from that single source file. I am confident that this s within MadCap Flares capabilities.

I am concerned about what you stated about reviewing Madcap content. Are you certain about that? I am referring to SME's and other stakeholders reviewing content. It seems rather implausible that MadCap Flare doesn't offer a way for content review without Flare. It would be practical to require Flare on a reviewer's computer.

BTW, Sphinx is an open-source reStructuredText documentation system. http://www.ibm.com/developerworks/libra ... #resources
My biggest concerns about this tool are the limitations (and difficulties) in creating professional looking documentation.



Thank you

[NorthEast]

No, a wiki is not a suitable way to create documentation, especially full sized manuals. The tool I settle on, however, must be able to output a help file, wiki, or PDF from that single source file. I am confident that this s within MadCap Flares capabilities.

Well, the purpose of a wiki is for collaborative authoring; and it sounded like your main requirement was for that - i.e. a team of authors to be able to contribute without using specific tools, across multiple platforms.

Flare is a good single-sourcing tool, and can generate web-based help (WebHelp, HTML5 help) and PDFs.
But note that Flare cannot create a wiki; although I don't really understand that requirement, because the point of a wiki is for the authors to maintain the content in the wiki itself.

I am concerned about what you stated about reviewing Madcap content. Are you certain about that? I am referring to SME's and other stakeholders reviewing content. It seems rather implausible that MadCap Flare doesn't offer a way for content review without Flare. It would be practical to require Flare on a reviewer's computer.

I didn't say that you can't review content. Your requirement was for others to be able to edit the content without requiring special tools and also using Linux systems, and I said Flare would not work in that scenario. Authors working on a Flare project would all need to use windows-based MadCap tools - either Flare itself, or Contributor (to produce content which is managed by a Flare author).

[sconnelly]

I'm an idiot.

What I mean to ask is... Does Madcap Flare offer an OS agnostic review mechanism where content changes (in the form of comments) can be inserted.

All that I am looking for is a way for engineers (who are mostly using Linux) to see content (in progress) and add un-line comments to the documentation. That is a basic requirement of any good documentation tool.

Finally, if I can get that requirement settled, will Flare play well with git source control?

Thank you so much

[RamonS]

As far as I can tell that is a No for both questions. You need workarounds, such as providing output from Flare that can be annotated on Linux (such as PDF), but that means that you need to transfer the comments manually to the Flare project. And Flare knows nothing about Git, so you would need to handle the source control externally. Welcome to the Microsoft only .NET world!

You could try and see if MadCap Contributor runs on Mono....

[sconnelly]

Thanks RamonS,

But your answer is plurplexing. How does one allow SMEs to review, in progress, Madcap content?

It isn't practical to require SMEs own Madcap Flare or even require them to download any special tool to enable reviewing and commenting of content.

Thank you.

[whunter]

I'm guessing that most people generate a Word or PDF file from Flare and send that out for review, and then deal with the feedback as needed when it comes back.

I rarely have feedback from reviewers that I would want to incorporate word for word anyway...usually they just make a comment or point out something and then I decide what needs to be done about it and how to word it.

[RamonS]

I agree with whunter. It all depends on how much contribution the SMEs make. If it is more along the lines of dropping a few comments then using Word or PDF files is fine, even paper copies. If SMEs write a good portion of the content that is to be taken as is (e.g. for legal reasons) then these contributors need a better tool. For that purpose MadCap created MadCap Contributor, which is 'Flare light'. The content creation part is provided, but not generating output or the tools to put the help plumbing in place.

If it is reasonable for SMEs to download a special tool is a matter of opinion. We use special tools for all kinds of stuff all the time because that way more features can be provided (although some claim so HTML5 for web apps is a far cry from a well-design desktop app). Which means of reviewing did you have in mind?
As far as MadCap goes, they are a .NET showcase company and tied at more body parts than just the hip to Microsoft's ecosystem. So it is either Windows or nothing....unless Mono works out as an option.

[sconnelly]

I appreciate your replies. Thank you.

I believe I may have found a suitable OS agnostic review tool, called Crocodoc.

As far as Contributor is concerned, it's requirements are unacceptable.

First, there is a licensing requirement... I certainly don't want to have to concern myself with licenses when I request content reviews.
Second, only Windows? Seriously, no one does it this way any more. I need reviews from people who only have Linux and Macs.

Disappointing.

But again, I really appreciate everyone's kind assistance.

Ty

[RamonS]

As far as Contributor is concerned, it's requirements are unacceptable.

First, there is a licensing requirement... I certainly don't want to have to concern myself with licenses when I request content reviews.
Second, only Windows? Seriously, no one does it this way any more. I need reviews from people who only have Linux and Macs.

Ty

There typically a license, even for FOSS you tend to have GPL or any other form of licensing. So I find it odd that you are using Linux and don't want to deal with any licenses.

As far as "only Windows" - 90% or even more of all desktops in the world run some flavor of Windows. I agree that this lopsided market share is bad for computing in general, but the Linux share is somewhere around 3%. If you want to offer a commercial desktop product, which platform do you target? As much as I loathe Windows that would be my first choice and given how difficult it is to create cross-platform applications I wouldn't even bother with Linux or the constantly declining share of OS X. If anything, I'd provide a browser based option. The more or less strong limitations of HTML5 / browsers and the haphazard implementation by the various browser makers aside, HTML5 is the way to bring an app to a variety of platforms including phones and tablets.
For many startups seeking investors (aka cash) the chances to obtain just that are much larger when focusing on a commonly used platform. Business reality often hampers or even destroys technical idealism.

Flare is not the tool for everything and everyone, but it works out quite fine for many.

[SteveS]

...As much as I loathe Windows that would be my first choice ...

</picks self up off the floor>

[RamonS]

...As much as I loathe Windows that would be my first choice ...

</picks self up off the floor>

Nobody gets fired for buying Microsoft, sad but true.

[sdcinvan]

I found this thread while looking for new threads to help out on.

Wow, I've come a long way since July. Still with my new company and have several docs under my belt now. The most significant Flare accomplishments to date are my documentation frame work, along with its 1000+ lines of stylesheet code for four medium output... as well as my automated push to our version control system and automatic document publication via MadBuild.

What I have learned with Flare v9.x:

Cons
- Flare is weak in regards css3 support
- Flare is weak with image, font rich, and odd print-out format publications
Trust me, my Quick Start Guide required a lot of precisely placed images, it is a accordion style fold document and Flare could not create this. Even MadCap's best people couldn't do what InDesign or FrameMaker
could easily accomplish.
Therefore, it is truthful to say that Flare v9.x cannot do everything that FrameMaker can do - yet.

Pros
- Despite the cons, Flare is awesome because it is, in many ways, more malleable... that is, if you learn basic html and css, you can make it bend to your will (within the limits of what is supported).
- Flare is FAST!
Once you have your framework or templates developed, you can generate content (simultaneously for multiple outputs) very quickly.
- Despite some .Net idiosyncrasies, Flare is very reliable. Even if there is a crash, all your content is in non-proprietary html and css.
- Open your mind and Flare will make you proficient in html and css. Trust me, rely less on the WYSIWYG and dive into the HTML code view, use NotePad ++ to edit the stylesheets and templates... you will soon realize the true power of Flare.
- IMHO, The learning curve for Flare is fast! I was relative proficient with Flare within three months and Adobe FrameMaker required a year or more.

Wish List
- A Flare web-based document review tool (as opposed to Contribute which is Windows only and must be installed).
- Improved graphics support so that I no longer require InDesign.

Bottom line, I do not regret my decision to shun my ten years of Adobe FrameMaker experience and put my trust in Flare (and risk my new job).

Have a nice day all!