Question

EDIT for clarity: this feature request is a market-discriminator. If Fogbugz can't help me here, I have to go with another product. This would be a huge disappointment as I already have Fogbugz in front of the technical experts working on the system. I'd like to make it easy for them to produce the parallel documentation. Fogbugz is a great tool for producing content. It's just the final deployment mechanism that is tripping us up.

I am looking for a Fogbugz plugin or workflow that would allow us to generate our online help text using the built-in Fogbugz wiki, export it to static HTML and then deploy it to remote no-network sites. We had been having the domain experts (who are also the developers) generate the text, after which documentation staff would import the text and format it in Robohelp, deploying to static HTML.

I'd like to eliminate that Robohelp step as it adds complexity without value.

The documentation requirements for our application are fairly straight-forward:

1. Each dialog box, major display, etc., has a "get help" button that we would like to be context sensitive: we'd like to click that button and be looking at the relevant content with minimal scrolling.
2. Our system has enough visual complexity that it's worth having a screenshot embedded in the documentation to serve as reference: e.g., the column that you see here with this name has values in it that refer to this measured quantity.
3. We have a few links between documents where it makes sense. For example, some of our displays slice and dice the same data in different ways. "This number in this display means the same thing as this vertical bar in this histogram," etc.
4. We run our system on several flavors of Windows and Linux so we'd prefer platform independence.

I would like to be able to produce the documentation in the Fogbugz wiki: that allows our developers (who are also the technical experts) to prepare the source material, respond to requests for clarification and so forth straight for their desks. At the same time, a documentation prep person can put boilerplate or standard formatting using the same wiki.

Here's what we're doing now:

1. Technical person writes original words in the wiki with relevant screenshots.
2. Documentation person copies that material into a Robohelp project using one of our limited number of Robohelp licenses.
3. Robohelp project is built into documentation during the CruiseControl-driven build process. Note: this builder application is Windows-only which is very frustrating since I would prefer to have an all-Linux production process.

So, the question is: can we get from the Fogbugz wiki directly to something like Robohelp-esque output? We don't need complicated features, user-defined tags or even fancy formatting. I'd be happy if we could just get our words and screenshots prepared with a little less frustration (and cost).

EDIT: Additional comment for clarity - currently, if the user clicks the question-mark button in our application, a browser appears with the context-appropriate online help material. Robohelp is the production mechanism used to produce the static content that appears in the browser. If there were another method to produce the static content directly from the wiki, we could eliminate the need for Robohelp entirely.

EDIT: Responding to one of the answers below suggesting that the deployed system access our Fogbugz repository dynamically and present the wiki content over the web. Sorry, this isn't possible. The Fogbugz wiki and the deployed system run on disjoint networks thousands of miles from each other. There is also a zero percent chance that I could deploy a complete copy of the Fogbugz system to the remote site. The request information stands at: how can we export the content from the wiki into a form readable by our remote system?

Answer 1

Have you considered changing step 2 from a manual process to an automatic script that uses the FogBugz XML api?

Answer 2

I feel like even without such a plugin, FogBugz already takes you about 90% of the way there, and the remaining 10% starts to get fairly application-specific. The challange of a general plugin, then, would be to be very accomodating.

If I were tasked to solve this problem, I would:

1. Create a wiki template which makes your wiki pages look exactly like how they should look for your end-users.
2. Apply that template to your docs (for dogfooding purposes). If an augmented template is desired for the developers (e.g., a search box), script this step.
3. When it comes time to deploy, I'd scrape the wiki pages* and generate a static wiki to export to your users. If I were averse to api's, I could write (or google for) a script to spider the wiki and dump the html to a folder. It'd be easier to use the xml api, plugin api, or sql queries for this step; there's no real reason to resort to screen-scraping.
4. I'd now run a script to process all of the stuff that I've dumped, and change the inter-wiki links to be consistent throughout my newly-invented structure. I'd probably want some sort of folder structure for storing the documentation, and there's nothing I could do to get around specifying this, so I'd need to massage things into whatever format I need.
5. Having gotten this working, I'd bundle this into my build/deployment scripts.

*While it would be neat to have an existing plugin which could provide the "scrape the wiki pages" functionality, it gets kind of tricky: there's a lot of specific use case functionality which might be desired. While a general-use plugin would be cool, I think it'd still just get you 91% of the way there. That is to say, to get exactly what you want, you'll need to do some post-processing or scripting regardless of what format the output comes to you in. I suspect that the ability to use the plugin api or the xml api to specify exactly what you want, as opposed to mostly what you want will pay off pretty quickly.

I think this is a neat plugin idea: click a button to package selected nodes of a wiki into a standalone static web page. It's interesting though, in that most situations have web access, in which case they can just use the FogBugz wiki (make it publicly visible, like this). My perception, then, is that people desiring this functionality would want it to be extremely powerful. I bet there's a contractor somewhere who would enjoy writing and selling this plugin. Maybe I should do that, hmmm....

Answer 3

You are looking for a script to run "in FogBugz" to export to your app - but I think the suggestion is to integrate your app by calling the XML API cmd=viewArticle, importing from the Wiki when the help button is clicked. The FogBugz API will serve up the HTML content of the pages that your app asked for, wrapped in the <sBody> tag of an XML response. Your app can then style the content and present it however you wish.

I know that a hand-waving explanation and you'll have some hurdles to overcome, but I think that's the essence of a solution.

Answer 4

I don't think this would be too hard (ha!); every wiki page is stored in the FogBugz DB as an HTML fragment – basically everything within the element is stored for each page (wiki article).
You'd need to process the data – e.g. convert the intra-wiki links, remove plugin elements, etc. – and you'd have to devise a suitable naming scheme for the articles/pages, but it's definitely doable.