Importing from Wiki structure

[owilkes]

For people who wonder if web authoring tools will become redundant with the advent of the Wiki, fear not.

My company thought Wiki was the way to go, and went through great pains to convert our user documentation into a Wiki (Mindtouch DekiWiki, since you ask).

It was not a good experience. We have now seen sense, and are getting out. Into MadCap Flare. Already, it seems much easier - the right tools for the job.

But we have to extract our current documentation - which is delivered as an html extract - into MadCap.

Any idea how we could do this? Have hundreds of pages of HTML, with hundreds of links between them - there doesn't seem to be a way of sucking up an HTML extract/website, and putting it into a MadCap Flare format.

Please don't make me do it manually.

Many thanks.

[LTinker68]

Well, if your links inside the files are relative instead of absolute, then you should be able to copy the entire site into Flare's Content folder (the Content folder at the root of the project folder) and the links will be fine, so long as you don't rearrange files and folders before copying over.

You do need to open the HTML files in the XML Editor so that Flare can run some conversion on them, which puts some tags and attributes in the code behind of the files. If you do that on a couple and compare the code in those files to the code in a couple of unconverted files, then you might be able to see what changes Flare is making to the files and use find-and-replace to make those changes against all the topics.

BTW, that's assuming you're not using a frameset in the site that you're moving to Flare. That makes things a bit more complicated.

[owilkes]

Many thanks for the quick reply. Links are indeed relative, so no problem there.

Sadly Madcap hangs when I link it to the root folder of my content folder. Has been hanging for a couple of hours, anyway. Its quite a large site. May load it into Sharepoint and see if that helps in any way.

Sadly also there is a load of unnecessary junnk that DekiWiki felt it was necessary to deposit all over our web pages, so we'll need to find some way of stripping that out. You wouldn't know any useful tools/tips for mass cleaning a few thousant html pages, would you?

thanks again.

[RamonS]

I know the proposal has an awful taste, but you need to make sure that you don't spend weeks of time finding a solution that gets you half the way there and then needs more weeks for cleanup as opposed to less time with some good ol' fashioned copy/paste followed by applying the proper styles (a step necessary no matter what).
The hang on import is possibly due to the gunk or incorrect coding in the topics. Maybe you can look into importing the pages into Word or using a virtual printer to print the content to some hopefully cleaner HTML. Unfortunately, Flare follows the same rules as many other systems: garbage in, garbage out.

[mgray]

I am looking into doing the SAME thing, from the SAME wiki company (what a mess!). Did you have a successful migration? Can you share your experiences and any advice?

[MinnesotaCory]

I imported about 1000 topics from a Confluence Wiki. After examining the confluence style sheet I created the styles that I needed, this eliminated the need to apply different styles.
As far as removing the unnecessary junk, I did some find and replace (replace with nothing) along with a little manual clean up on every topic.
I used the "import HTML files..." option to import the files one folder at a time and was able to maintain most of the links within each section of the wiki. Cross-section links were repaired manually.
Analyzer was an invaluable tool for fixing styles and finding broken links/bookmarks.

I apologize for not having any shortcuts.
-CK

[mgray]

Thanks for your response. How are you providing your end product?

[MinnesotaCory]

I output a Knowledge Base using WebHelp. It is an intranet site with data about our client's products and services.

[wbrisett]

Another option is to have a custom script written that will take the WIKI content and format it into something that is more of a standard for Flare's import. I've done this several times now and always end up with DITA output. That way I don't have to mess with any clean up. I just have to format my css correctly for the content.

Wayne

[owilkes]

Just to document our experiences and lessons learned...

After a few weeks of abortive attempts at finding a quick conversion - including search-and-replace and scripting, we bit the bullet, hired some temps and did manual copying and pasting... cheaper than wasting more time.

A few tricks we picked up:

1. Copying html pages (copy as HTML) - use Firefox, rather than IE or Chrome - as the links to the images will also be copied (unfortunately, with an absolute link).
2. You can fix these images and get them into the project, by going to Project --> Import HTML files, and importing these topics to copy over themselves - this then moves the images to the images folder (or use subfolders, as having too many images in one folder causes performance issues). Note - this can break links, so do this first before fixing wiki links.
3. Dragging and dropping topics onto links is the quickest way to fix links.
4. Analyzer is your friend - but we found using a 64bit rather than 32 bit computer is better at not constantly re-scanning the project whenever a topic is fixed. Generating reports - then export to XL.
5. You can use Analyzer to delete unwanted styles that you haven't used.
hth
Thanks.

[AaronF]

Oren,

I'm sorry you didn't have a great experience with MindTouch. So much of a users' experience with server software is driven by the admin that setup the site. Also, because you called it "Deki Wiki" it tells me you were using a very early version of MindTouch and not a commercially supported build. I.e.- you were using the free community version, which could have been configured with collection of extensions and not properly deployed.

I hope at some point you'll take another look at us. Here's a short product tour: http://youtu.be/BM0-B8HSo68 I hope you'll take a look.

Most of all, thanks for verbalizing your frustration. It seems it may have been the impetus for Madcap developing a converter, which completes the 2nd half of a round trip story for those who prefer a desktop authoring environment to a web based one.

~ Aaron, from MindTouch.

[owilkes]

Hi Aaron,

We were using the paid version. We paid more for mindtouch than we did for Flare, and the results are incomparable. It might have been improperly deployed - but we also spent a lot of money on consultants and inhouse coders, to try to get what we needed (which it didn't do by default), further increasing our cost. It was pouring good money after bad. Flare does what we needed, out of the box.

I'm sure dekiwiki must be good for something - but it wasn't developing documentation to be supplied to clients - we couldn't even provide a portable version relying on further 3rd party systems, and was a painful dead end for us, impossible to get out of without lots of manual copy and paste.

[doc_guy]

It seems it may have been the impetus for Madcap developing a converter, which completes the 2nd half of a round trip story for those who prefer a desktop authoring environment to a web based one.

I haven't seen or heard of the converter you're talking about. Can you tell me more? (A search for "wiki converter" in the forums only pulled up this post.)

[cayennep]

So, solved my own problem, with help, sharing here...

Discovered you need a TOC in the Word doc before importing, in order for Flare to create a structured TOC.

Either previous versions of Flare OR another tool required me to remove the TOC, and it's not documented in Flare help, so it simply didn't occur to me that the structure comes from the Word TOC, rather than the document structure and headings.

hope this helps someone

[jacob6080]

If you do that on a couple and compare the code in those files to the code in a couple of unconverted files, then you might be able to see what changes Flare is making to the files and use find-and-replace to make those changes against all the topics.


-----------------------------------------------
EMR Software

[AaronF]

we couldn't even provide a portable version relying on further 3rd party systems, and was a painful dead end for us, impossible to get out of without lots of manual copy and paste.

That's strange because MindTouch stores all content natively in XHTML and has the ability to output to XML, PDF and JSON. I'm not sure why you would need to copy/paste anything. There's also an API first approach to MindTouch; meaning there is a REST interface built first, before a user interface. This makes things like automation and import/export a snap.

but we also spent a lot of money on consultants and inhouse coders, to try to get what we needed (which it didn't do by default), further increasing our cost.

I'm not sure if you were aware of this, but you were using MindTouch Platform. This is a development framework and is very different from our MindTouch TCS product, which is a purpose built product for documentation. MindTouch TCS is what SAP, SuccessFactors, SugarCRM, ExactTarget, Paypal, Accenture etc use for their "user manuals" and documentation. I can imagine you did do quite a bit of work on MindTouch Platform because it's the "Platform", the development framework.

Flare does what we needed, out of the box.

That's great. IMO, Flare is the best of class for desktop authoring of tech docs.

[rob hollinger]

We have given this script to a few people who have had success extracting their content from MindTouch Wiki sites.
It was built by an old employee and is a python script.
We cannot support it, but if you know someone who knows python scripting it might help speed things up a bit.

http://ts.madcapsoftware.com/downloads/ ... n-Tool.zip

[owilkes]

That's strange because MindTouch stores all content natively in XHTML and has the ability to output to XML, PDF and JSON. I'm not sure why you would need to copy/paste anything. There's also an API first approach to MindTouch; meaning there is a REST interface built first, before a user interface. This makes things like automation and import/export a snap.

But not webhelp - or anything portable, as far as we could find. Had to use HTTRACKER to actually get the stuff out.

Trust me, we tried several approaches. Maybe there was a way, I set one of my guys to try - and try - and try again, while the performance was killing us and management getting ever more exasperated. The support was far more expensive than Flare (we didn't have many tickets, after the cost of the licence) - and as previous support had failed to resolve our issues, buying more support risked pouring more money away. It may have been our own customisation and coding, which we had to do to get the functionality we wanted, that then trapped us inside it. By the end, we were just desperate to get out. I asked around the flare forum, and got the same response.

but we also spent a lot of money on consultants and inhouse coders, to try to get what we needed (which it didn't do by default), further increasing our cost.

I'm not sure if you were aware of this, but you were using MindTouch Platform. This is a development framework and is very different from our MindTouch TCS product, which is a purpose built product for documentation. MindTouch TCS is what SAP, SuccessFactors, SugarCRM, ExactTarget, Paypal, Accenture etc use for their "user manuals" and documentation. I can imagine you did do quite a bit of work on MindTouch Platform because it's the "Platform", the development framework.

Trust me, after the cost and expense - we're not going back to MindTouch again. Maybe companies with either money to burn, or very limited requirements that fit what whatever it does - but one savaged, twice shy.

Flare does what we needed, out of the box.

That's great. IMO, Flare is the best of class for desktop authoring of tech docs.

I haven't seen anything comparable online. Maybe we screwed up - but the same people who screwed up (well, fewer, as a few lost their jobs over the mindtouch debacle), have made a big success of flare.

Which isn't saying Flare is perfect - from performance, we would prefer a server-approach. But far rather go from rich, user-friendly client into a database, than the other way round.

[novice]

Simply, can somebody please summarize the steps required to import Confluence wiki pages to Flare and create PDFs and online help? I am a newbie and I am pretty much confused with this discussion here.

[jdw2465]

We've had issues with getting our CHM files into MindTouch. Add the rather heavy, annual cost for hosting and Flare is winning hands down. Sad though, since MindTouch does offer some very interesting analytics, social, and KB functionality. But if you want CSH, plan on paying even more than you did for the initial hookup. If Flare can offer some of those same solutions, it's one more nail in the MT coffin. Makes me wonder if MT is paying enough attention to MadCap's bleeding edge feature research and implementation.