Page 1 of 2
Documentation
Posted: Wed May 10, 2006 11:12 am
by Todd_Z
When you're developing a piece of software with many sections, a complex database, and an export tool for example, what are the methods you use to create documentation?
I'm looking to create a simple, yet complete set of doc for the system I am building.
Posted: Wed May 10, 2006 11:36 am
by Maugrim_The_Reaper
Posted: Wed May 10, 2006 11:56 am
by Todd_Z
I don't mean the source code, I mean front end documentation, so that the user will know how to use each page, view all the features included.
Posted: Wed May 10, 2006 12:50 pm
by jmut
UML?
Posted: Wed May 10, 2006 12:55 pm
by Maugrim_The_Reaper
I still go with my first suggestions as a starter (practically essential if your code is OO based and works from a standardised API). At least its my first port of call after reading any "quick start" guides...
For the rest I usually plan out the documentation based on what features are public (phpDoc will outline most), write each section quickly (I don't bother being careful or proofreading or second guessing - just write it and get it done with), and read it through. After that I get down to improving, filling in blanks, clearing up confusion - all works out well if the initial plan was good and not departed from.
I might then consider transferring into the DocBook XML format from which I can generate PDF, CHM or HTML versions of the documentation for easier downloading and viewing by end users.
Posted: Wed May 10, 2006 12:56 pm
by Maugrim_The_Reaper
Most end users, unless specifically aimed at programmers will rarely understand UML fully...
Posted: Wed May 10, 2006 1:03 pm
by timvw
End-user documentation:
I try to add all the help meesages in rhe app itself (eg: contextual msgboxes) instead of in a separate document.
Afterwards i make screenshots of all the screens and explain which and how tasks can be performed from there...
Developer documentation:
A combination of ERD/UML/generated API docs/unit tests/... Depends on the fact which design decisions i found important enough to document them...
Posted: Wed May 10, 2006 1:46 pm
by RobertGonzalez
What I do is use the app. Use it how the end-user would use it, snag screenshots of each step, add lists of potential functions and capabilites, then compile it in to a document. Depending upon your organization, you can use Powerpoint, Word or PDF. Or you can use any other variation of office software to convey the methods of use of the app you developed.
For documentation, simple, easy to understand words with lots of pictures is usually the best way to go.
Re: Documentation
Posted: Wed May 10, 2006 4:46 pm
by Christopher
Todd_Z wrote:When you're developing a piece of software with many sections, a complex database, and an export tool for example, what are the methods you use to create documentation?
For that -- Wiki.
Posted: Wed May 10, 2006 5:38 pm
by Chris Corbyn
I just write mine by hand in Plain-text and HTML formats.... I don't enjoy it and right now I'm wondering why I'm not using phpDocumentor

Posted: Wed May 10, 2006 10:29 pm
by neophyte
phpDocumentor is on my "must learn list" too....
I confess, if I'm writing for myself I comment nothing... 8o....

Posted: Thu May 11, 2006 12:19 am
by alvinphp
timvw wrote:End-user documentation:
I try to add all the help meesages in rhe app itself (eg: contextual msgboxes) instead of in a separate document.
Afterwards i make screenshots of all the screens and explain which and how tasks can be performed from there...
This is pretty much what i do also. I create a word doc help file that explains the features of each page or sometimes make a simple web version of it. Really depends on the situation and/or requirements.
Todd_Z wrote:When you're developing a piece of software with many sections, a complex database, and an export tool for example, what are the methods you use to create documentation?
I don't mean the source code, I mean front end documentation, so that the user will know how to use each page, view all the features included.
I don't really use a special tool to do this and not sure what kind of method it would be. I guess you can call it procedural word processing method.

Posted: Thu May 11, 2006 3:48 am
by Maugrim_The_Reaper
At the end of the day there is no magic documentation tool for end users. You just need to dig in and write it, edit it, and format it.
Posted: Thu May 11, 2006 6:34 am
by jmut
Maugrim_The_Reaper wrote:At the end of the day there is no magic documentation tool for end users. You just need to dig in and write it, edit it, and format it.
I guess because there all kind of users

They need to see same thing from different aspects.
Posted: Thu May 11, 2006 8:41 am
by RobertGonzalez
The easier to understand, the better. Even if there are different types of users, if you can reach the most comuter illiterate grou of users, everyone could feasibly stand a chance at understanding your. It is tough. I know. I have been writing user guides for some folks at work that I think my 5 year old daughter could read and understand.And even these can go over their heads sometimes.
But I think if you target the entry level users, and if you can get close to reaching them, your docs should be golden.