Documentation
Moderator: General Moderators
Documentation
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.
I'm looking to create a simple, yet complete set of doc for the system I am building.
- Maugrim_The_Reaper
- DevNet Master
- Posts: 2704
- Joined: Tue Nov 02, 2004 5:43 am
- Location: Ireland
- Maugrim_The_Reaper
- DevNet Master
- Posts: 2704
- Joined: Tue Nov 02, 2004 5:43 am
- Location: Ireland
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.
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.
- Maugrim_The_Reaper
- DevNet Master
- Posts: 2704
- Joined: Tue Nov 02, 2004 5:43 am
- Location: Ireland
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...
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...
- RobertGonzalez
- Site Administrator
- Posts: 14293
- Joined: Tue Sep 09, 2003 6:04 pm
- Location: Fremont, CA, USA
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.
For documentation, simple, easy to understand words with lots of pictures is usually the best way to go.
- Christopher
- Site Administrator
- Posts: 13596
- Joined: Wed Aug 25, 2004 7:54 pm
- Location: New York, NY, US
Re: Documentation
For that -- Wiki.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?
(#10850)
- Chris Corbyn
- Breakbeat Nuttzer
- Posts: 13098
- Joined: Wed Mar 24, 2004 7:57 am
- Location: Melbourne, Australia
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.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...
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.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.
- Maugrim_The_Reaper
- DevNet Master
- Posts: 2704
- Joined: Tue Nov 02, 2004 5:43 am
- Location: Ireland
- RobertGonzalez
- Site Administrator
- Posts: 14293
- Joined: Tue Sep 09, 2003 6:04 pm
- Location: Fremont, CA, USA
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.
But I think if you target the entry level users, and if you can get close to reaching them, your docs should be golden.