Hi Neil For non-technical documentation I have found macromedia Captivate very useful, alot of non technical users want to just see the gui in action for a specific task and Captivate handles this perfectly, I've found many users dont read documentation fully anyway.
The visual approach Captivate gives keeps the users attention, plus you can convert any presentations to word/pdf if you wish. >From a developer doc route a wiki sounds the route to go as mentioned by the other guys. HTH Jose Diaz ;) On 6/8/06, Nick de Voil <[EMAIL PROTECTED]> wrote: > > > How do you guys go about technical documentation, how do you write docs > that > > tell other people (not necessarily technical, but project participants) > how > > your code works, what the rules are, what the re-use potential is, how > the > > UI works etc. > > > > What tools do you use for the job? Word? Visio? Wiki? How do you > tackle it > > and when? Before writing your code? After? > > For us, the exact set of documentation deliverables is very > project-dependent > and is thrashed out at a high level at project initiation time and then in > more > details at the beginning of each project stage. It depends on the > complexity of > the job, the customer's expectations and the development method used for > the > project, but in general you need to have documentation tasks in all three > places - beginning, middle and end. You need to document the functional > and > "non-functional" (performance etc) requirements up front or the project > will > fail. You need to document what you're doing at each stage in order to > have a > managed process (imo this is true even if you're doing "agile" > development). And > you need to document what you've done at the end, or the documentation > will not > reflect reality. > > We do still use Word/PDF for those documents where a simple, visible > version > control scheme is critical. We store everything in our web-based project > support > environment as a central reference point. Being basically a CMS, besides > storing > files it allows you to create more free-form web-based documentation as > you go > along, whether as traditional pages or blog/wiki/forum/helpfile entries. > It also > creates interactive diagrams. We use a lot of diagrams because they are > information-rich and (some) customers can understand (some of) them. We > use all > sorts of diagramming techniques, both from UML and older toolsets. > > The only thing I would caution against is creating too many detailed > how-to > documents with embedded screenshots - they become a real pain when you > want to > change things. An up-to-date Captivate demo is much more likely to be > correct > and consistent. However, sometimes customers want things on paper. > > Nick > > > > > > > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Message: http://www.houseoffusion.com/lists.cfm/link=i:4:243039 Archives: http://www.houseoffusion.com/cf_lists/threads.cfm/4 Subscription: http://www.houseoffusion.com/lists.cfm/link=s:4 Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.4 Donations & Support: http://www.houseoffusion.com/tiny.cfm/54
