[Interest] Advise on setting up documentation for a project (Qt Help Framework or not)

Elvis Stansvik elvstone at gmail.com
Thu Oct 13 16:16:21 CEST 2016

Hi Andy, and thanks for sharing.

2016-10-13 15:16 GMT+02:00 Andy <asmaloney at gmail.com>:
> Elvis:
> I write my manual & tutorials in HTML using a text editor - I use Atom or
> TextWrangler - depends what I'm doing.  I include the HTML/css with my
> application in a Documentation directory.
> In my application I have items in the Help menu which open the HTML files in
> the user's browser.  I also include some of this content online so having it
> in HTML removes duplication of effort.

Alright, I'm considering doing something like this myself. The reason
I was considering pandoc or something else (like Sphinx/reST) was to
save some typing, and also the possibility of PDF output. But maybe
it's not worth it at this point (the User Guide will be quite short
initially). I also see now that Sphinx support generation of a Qt .qhc
help collection file.

> I do not provide PDFs as well - I figure if they want a PDF they can "Print
> to PDF" and it's one less thing for me to maintain/verify/include.  The
> documentation includes css which includes proper pagination and formatting
> for printing/PDF.

That's a good point, though I think my target users are quite
PDF-oriented and might not know that they can get good output by
printing to PDF.

> (FWIW I work in a very niche market.  I might choose to do something
> different if I were writing something for mass consumption or had a lot more
> resources.)

My market is quite niche as well :) (we're doing a machine for
analysis of minerals in drill cores and this is for the visualization
tool for looking at the result).

> Good luck!

Thanks, and thanks for the input.


> ---
> Andy Maloney  //  https://asmaloney.com
> twitter ~ @asmaloney
> On Thu, Oct 13, 2016 at 3:37 AM, Elvis Stansvik <elvstone at gmail.com> wrote:
>> Hi all,
>> Sorry if this is a bit of a stream-of-conciousness style post.
>> I've started considering providing a manual for our (Qt desktop
>> widgets) application.
>> I'm interested in what others have done.
>> Qt has its Qt Help Framework, which AFAICS gives mostly the benefit of
>> being able to interact with the help/manual content using its API
>> (e.g. for What's This? or showing the full manual inside the
>> application).
>> In my case, I think we want to also provide the manual online on the
>> web, and allow for the manual for a certain release to be updated on
>> its own schedule, separate from the application.
>> I imagine URLs like:
>>    /doc/<ourapp>/manual/0.4
>>    /doc/<ourapp>/manual/0.5
>>    ...
>> on our website.
>> Is anyone using Qt Help and also providing the same manual online? Any
>> gotchas I need to think of when using the same source HTML for online
>> viewing and the compressed Qt Help file? If you're doing something
>> similar, what are you using for authoring the HTML? Nothing? I was
>> thinking maybe pandoc..
>> Should I have a separate repo for the manual, with a branch for each
>> release we do? (published to the URLs above).
>> All in all, I'm very interested in how all of you Qt Widgets using
>> folks do your user manuals, if you use Qt Help or not, and if you
>> publish in other ways. E.g. do you provide PDFs as well?
>> Thanks in advance,
>> Elvis
>> _______________________________________________
>> Interest mailing list
>> Interest at qt-project.org
>> http://lists.qt-project.org/mailman/listinfo/interest

More information about the Interest mailing list