Documentation

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

User avatar
Todd_Z
Forum Regular
Posts: 708
Joined: Thu Nov 25, 2004 9:53 pm
Location: U Michigan

Documentation

Post 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.
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post by Maugrim_The_Reaper »

User avatar
Todd_Z
Forum Regular
Posts: 708
Joined: Thu Nov 25, 2004 9:53 pm
Location: U Michigan

Post 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.
jmut
Forum Regular
Posts: 945
Joined: Tue Jul 05, 2005 3:54 am
Location: Sofia, Bulgaria
Contact:

Post by jmut »

UML?
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post 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.
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post by Maugrim_The_Reaper »

Most end users, unless specifically aimed at programmers will rarely understand UML fully...
timvw
DevNet Master
Posts: 4897
Joined: Mon Jan 19, 2004 11:11 pm
Location: Leuven, Belgium

Post 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...
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post 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.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Documentation

Post 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.
(#10850)
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Post 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 :?
User avatar
neophyte
DevNet Resident
Posts: 1537
Joined: Tue Jan 20, 2004 4:58 pm
Location: Minnesota

Post by neophyte »

phpDocumentor is on my "must learn list" too.... :oops:

I confess, if I'm writing for myself I comment nothing... 8o.... :roll:
alvinphp
Forum Contributor
Posts: 380
Joined: Wed Sep 21, 2005 11:47 am

Post 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. :roll:
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post 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.
jmut
Forum Regular
Posts: 945
Joined: Tue Jul 05, 2005 3:54 am
Location: Sofia, Bulgaria
Contact:

Post 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.
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post 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.
Post Reply