> 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/ --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
