Re: Documentation tool

Álvaro G. Vicario wrote:
I've been considering using phpDocumentor to document a web app I'm working on. Apart from parsing inline comments in the code itself it allows to maintain external docs, and I need to deliver end-user documentation in a format like MS-Word or PDF. However, I'd need to write these external docs using DocBook, an XML format I've never used.

I wonder if there's another tool that would suit my needs better. I don't really need to document the code itself, just produce a couple of manuals with installation and usage instructions. My notes are currently in plain text files but these are ugly to print and can't have images (such as screenshots or diagrams). A Word processor would not be source control friendly.

Googling has confused me with the thousand documentation tools that seem to exist...



When documenting a manual of use for your programs its really a difficult choice .

When I was a working man , I had document all sorts of things , at first I was using word, then made xml documents that where modified by a script , then it all got moved to a share point so i ended up going back to word.


Now that I have gabbs of free time , I have started my own projects and I have had to consider making one a foss project, I discovered the beauty of wiki type systems.The advantages of a wiki is that it can be group written , can include screen shots and it can store previous revisions of your documentation.

The reason I've pegged a wiki is that the learning curve for actual use is small , allowing you to spend time writing and taking screen shots.

This is all good ,while developing the manual it the added bonus that it can be a online for your clients to use right now.

There is no real reason you can't - wiki -> copy+paste to word / print to pdf.

At the moment I work solo and don't develop for commercial use .My suggestion may be completely rubbish for a large project and for business use.

Thats my 2c .

regards trookat
.

Relevant Pages

  • Re: documentation for novice and newbies
    ... That was a problem in the documentation. ... something like "For Novices and Newbies to Debian". ... Under this we could have individual wiki entries that we could work on. ... To the extent we use GPL, ...
    (Debian-User)
  • Re: -Crawl- -Stone Soup- Release Announcement (yes, Release Announcemen
    ... one person doing the documentation or that online thing. ... person") without using a wiki. ... but will mention any contributers in the credits (every ...
    (rec.games.roguelike.misc)
  • Re: Angband documentation project
    ... referring to off-line documentation. ... The documentation is mostly likely to be referred to immediately after ... This makes sense - however the Wiki edit history is probably easier to determine ... PDF, HTML etc. ...
    (rec.games.roguelike.angband)
  • Re: Angband documentation project
    ... Given that my plans involve making the help external HTML files (with ... Using a wiki isn't that great for this, ... the documentation is currently distributed as, ... helpfiles are probably GPL, though that's not really that appropriate ...
    (rec.games.roguelike.angband)
  • Re: User comments on python.org
    ... >> comments be included inline as an SSI? ... documentation has problems, the domain is inherently confusing or large ... (perhaps linking to other Wiki pages that go on at length on a topic). ... I think it will be better when the comments are included inline, ...
    (comp.lang.python)