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

[Andy]

On Thu, Oct 13, 2016 at 10:16 AM, Elvis Stansvik <elvstone at gmail.com> wrote:

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

Oh - one thing I tried but ultimately rejected for my project was Scrivener
(https://www.literatureandlatte.com/scrivener.php).  It has the nice
property of being able to export to a lot of formats (eBook, PDF, webpage,
etc.) and at the time I was thinking users might want to have a nice eBook
of the manual on their mobile device.

The drawback for me was that I use a lot of images and that made working
with it a bit cumbersome.  That was a number of years ago, so it might be
better now.  Might be worth looking at depending on your use-case.


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

That's...  pretty niche :-)


>
> >
> > Good luck!
>
> Thanks, and thanks for the input.
>
> Elvis
>
> >
> > ---
> > 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
> >
> >
>

---
Andy Maloney  //  https://asmaloney.com
twitter ~ @asmaloney <https://twitter.com/asmaloney>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20161013/91dd0431/attachment.html>