On 5 mar, 23:54, Tim Chase <[EMAIL PROTECTED]> wrote:
> > I'm building a complex Web site using Django of course, and I
> > have to start the documentation this week. I'd like some
> > suggestions about this. I want to make the documentation
> > available through the web and a PDF file.
>
> I've found that there are two over-arching categories of
> documentation:
>
> -developer documentation
> -end user documentation
>
> For the former, rest2html or some other means of extracting
> docstrings is great. It may not offer PDF, but most developers
> just want accurate, up-to-date, easy to reach information.
> Docstrings do that, and there are tools to export a walk of your
> .py files and emit programming documentation as HTML. I can't
> say I find this terribly helpful, but some folks like it. One
> key aspect is that it's intimately tied to the code.
>
> For the end-user documents, you're not tied so closely to the
> code, but rather tied to user-experience/flow. You can include
> screen-shots, add more hand-holding text, and do other such
> niceties. For this, something that produces nicer documents is
> in order: LaTeX and DocBook are the big contenders. You can
> produce all sorts of output from these (HTML, PDF, PostScript,
> and I understand there are even DocBook->LaTeX or Latex->DocBook
> converters). As Alex's message notes, you can use HTML->PDF
> converters. Personally, I merely tolerate PDF and much prefer
> HTML, so it's my first choice of documentation medium.
>
> I've found mind-mapping software (many are available, but I've
> taken to Vym[1]) helpful for organizing out the user
> documentation. Some even have an export-to-$FORMAT
> functionality, such as Vym's direct-to-HTML output. It also
> supports direct-to-LaTeX, and since the file-format is just
> zipped XML (plus supporting files), it wouldn't be too hard to
> write an XSLT template to remap it to DocBook too.
>
> -tim
>
> [1]http://www.insilmaril.de/vym/
In my case it's end-user documentation, with a lot of screenshots. I
think I'll give docbook a try, or maybe Latex, not sure right now.
Thank you.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django users" group.
To post to this group, send email to django-users@googlegroups.com
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-users?hl=en
-~----------~----~----~----~------~----~------~--~---
