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

[Andy]

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.

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.

(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.)

Good luck!

---
Andy Maloney  //  https://asmaloney.com
twitter ~ @asmaloney <https://twitter.com/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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20161013/77bcf910/attachment.html>