Can anyone recommend me a documentation platform? In the past I've used MediaWiki for my software, but I'd like to provide offline documentation as well. The most important features it has to support are a search feature and customized syntax highlighting of inline code samples. I need it to document both user interfaces and code APIs. The documentation software doesn't have to be free/open.
I use help and manual. Built with Delphi and does a nice job with manual and help file generation from same source.
ReplyDeleteI've heard good things about www.doctohelp.com
ReplyDeleteThere's also HelpNDoc (http://www.helpndoc.com) which, like Help and Manual, allows the creation of multiple output formats, including on-line docs, from a single source. It's also a lot less expensive than Help and Manual.
ReplyDeleteHowever, I don't think either of these product provides for the auto/custom syntax highlighting you can get in some of the wiki products.
Have you looked for a plugin or 3rd party product that would export your existing wiki to a downloadable format such as PDF? I know that DocuWiki has one, but I haven't used it.
I'm working on overhauling my application, so my wiki is no longer up to date. I've tried Help and Manual, but it doesn't seem to agree with me.
ReplyDeleteEDIT: HelpNDoc looks really good, but it doesn't look like it supports syntax highlighting. I'll have a look at doc to help.
Also worth looking at Precision Helper: http://www.be-precision.com/products/precision-helper/ Revised: It does NOT APPEAR to support syntax highlighting. It's free.
ReplyDeleteBill Meyer Precision Helper looks interesting, but I cannot find any information on the product website that indicates a syntax highlighting feature. Do you have more information on this or know where I can find it?
ReplyDeleteKevin Powick I have not yet used the product, so I do not have specific knowledge, but I may have drawn an incorrect conclusion from some of their claims.
ReplyDeleteThanks everyone for the suggestions, I'll certainly be checking these out. I'm also looking into writing a system in Delphi, integrated into my application, which gets the information from XML files. If it's not too much work, it might be a better solution. I can easily use my syntax control in read-only mode to display code and use some labels, panels and magic to display information...
ReplyDeleteGraeme Geldenhuys Sounds good, and the viewer looks nice, but did I miss reading what you use as a composition tool? ;) An editor, I mean, not the harvesting. If fpDoc is the tool, that would appear to work for those using Lazarus, but what of Delphi?
ReplyDeleteGraeme Geldenhuys I may need to explore the INF potential. I wold, however, move heaven and earth not to edit XML. ;)
ReplyDeleteFor the TortoiseSVN project we rely on DocBook XML to create the chm, pdf and html manual. We built an ecosystem around it that covers the localization part using gettext .po files. Works like a charm, but not out of the box.
ReplyDeleteMy favourite XML editor is notepad++ :)
Bill Meyer Writing docs in XML is not that bad. In fact I see it as an advantage because it forces you to think about structure and logical markup while writing. Many people are obsessed with formatting when writing docs. I leave that to the processing tools and the stylesheet.
Graeme Geldenhuys XML seems to me to fit the adage that when the only tool you have is a hammer, everything begins to resemble a nail. I have seen some truly ugly constructs where the characters expended in the tags far outnumber the actual content. That's just wrong.
ReplyDeleteGraeme Geldenhuys And that is the reason I mourn the loss of Sprint. Before Sprint, I used MS Word, and battled with it to get the format I wanted. For a long time, I kept thinking about roff, and dot commands, and that coupling a really good text editor with a really good output formatter would be terrific. Once you learned that the formatting could be trusted to work as desired, then you could simply focus on the content, and not worry over formatting.
ReplyDeleteI got my copy of Sprint, and over a long weekend, converted my then 100 page manual from Word to Sprint. The main task was removing all the many formatting overrides I had needed with Word. It was the most productive documentation tool I have ever used.
Then came Word for Windows, and WYSIWYG, and like most people, I found myself fiddling with appearance, and the content suffered for a time.
I agree that some help files are annoying to read. But worse, my routine complaint with help is that non-linear documents are much harder to proofread than linear, and that coverage is even harder to verify. Help extracted from embedded comments in code files is OK as far as it goes, but I really think there is a layer missing: once the help has been harvested, there should be an editing tool which allows for easily adding content that would have been clutter in code files.
Where is INF documented? Google returns a lot of false leads on that.
ReplyDeleteA better alternative to XML are the various wiki text formats, and other lightweight "directly readable" text-based formats. On the other hand, there are many of them and they're not standardized at all.
ReplyDeleteGraeme Geldenhuys Yeah, I am not likely to dive into Lazarus and FPC, just to get a doc tool. ;) I have sufficient adventures with one IDE!
ReplyDeleteGraeme Geldenhuys SO I downloaded the DocView for Windows, ran it, and clicked File Open to take a look at the IPFREF_v4.INF file, but as soon as I click File Open, I get the ever popular "List index (1) out of bounds." error. ;)
ReplyDeleteNot the most friendly viewer...
Graeme Geldenhuys My favorite excuse. ;) I am running on Win7-64. DocView 1.0. I do see Welcome to DocView. And I now know that it works. It was apparently not happy at running here from a network share, however, which is what I tried at first. I ordinarily expect that I should be able to do that, if a program does not have an installer.
ReplyDeleteI was running it from:
\\ATLAS\H_Atlas\__DL_Sfwe\IPF\docview_i386-windows with the error.
It now runs from:
E:\IPF\docview_i386-windows where it works as intended, I think.
Graeme Geldenhuys Glad I could enlighten you ;)
ReplyDeleteAnd even happier it was so easy to find the cause...
However, now I get this:
Could not open : Invalid file header
Graeme Geldenhuys Looking at the IPFREF_v4.INF file in a text editor, it appears to be HTML. Er... scratch that, I figured out my error.
ReplyDeleteGraeme Geldenhuys I am seeing a very interesting rendition of a window in the IPF reference. The top 1/3 or so is diagonal lines, as if a TV set had lost horizontal lock. (Yes, that was before HD, and digital video, and stuff.) ;)
ReplyDeleteGraeme Geldenhuys My pleasure. I thought at first it had to do with whether the whole image was in view, or partly obscured by window limits. But no, and it seems that in that file, at least, every one of the dialog images presents either (not often) that diagonal lines mess, or more often, the upper roughly 1/3 in just black. Very odd.
ReplyDeleteAlso, in the text, it mentions using metafiles, but I found no specifics as to which particular metafile format might be compatible....
What are you, the one man DocView team?
Graeme Geldenhuys Ah, I see. That explains some other things I noted in the images. I wasn't digging deeply, as it's not my challenge to fix. ;) Sounds like some odd sort of array or matrix indexing error... Is it painted from the bottom up?
ReplyDelete