[Interest] Advise on setting up documentation for a project (Qt Help Framework or not)
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>:
> 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
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
>> 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:
>> 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,
>> Interest mailing list
>> Interest at qt-project.org
More information about the Interest