| Author |
 Topic  |
|
gor
Retired Admin
Netherlands
5511 Posts |
 Posted - 30 September 2000 : 11:09:56
|
Ok,
Since I won't be coding the next few releases, time for something I think we need even more than more features:
(Better) Documentation/ Manuals/ FAQs/User Instructions/Installation Manuals
We can't call this a good professional product if it doesn't good documentation (I think).
I don't have much experience with writing documentation but from what I've seen the way to go is to use some generic structure preferably in the form of a XML file and then use a parser to compile a HTML version (devided into online help for the user or the administrator) a RTF version, PDF version etc. of the manual.
With a standard structure and a flat-file solution different members could make parts (maybe in different languages) of the manual that could be merged into the "master-manual".
Ofcourse the structure would provide a system of giving credit to all the authors.
Now I could start setting up a structure just for the manuals for this forum, but if anyone has a better idea about how to proceed, lets hear it.
Pierre Gorissen
Experience is that marvelous thing
that enables you to recognize a mistake when you make it again.
F.P.Jones
[moved by admin 10/18/2000]< |
|
|
Greybeard
Starting Member
USA
19 Posts |
Posted - 30 September 2000 : 20:33:30
|
I agree that documentation should be a major push right now. I have done a lot of techinical writting for satellites but have never delved into XML, yet If documentation is going to be developed then I do have a few suggestions.
1. Stop forum developement until the documentation catches up. It is a royal pain to try and catch up with coders.
2. Strict version control. Once the docs are done, make a copy and set it as the dev docs, updating it as code is written. That way when a new release comes out the docs for that release are also available without losing the earlier version docs.
3. Don't reinvent the wheel. I'm sure that there are systems or scripts already out there that will do the job without having to write something new. A slightly modified version of this forum (without all the bells and whistles) might even work.
4. Must have search capability.
5. Put it on-line instead of distributed. This helps maintain configuration control. Just add links to the on-line docs.
Well that's my 2 cents
Chuck Murison< |
 |
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 30 September 2000 : 22:31:44
|
As for stoping forum development... thats not something to do just yet... but I will be taking the source code offline for a few weeks... and implementing "Internationalization" and "CSS"
then it's strictly debugging... which is where the documentation team(s) can go hog wild... meaning no new features... just bug work... which is not adding new features... or how the forum works... it's just a matter of making everything work as advertised.
Reinsnitz (Mike)
http://forum.snitz.com
reinhold@bigfoot.com
><)))'>
"For God hath not given us the spirit of fear; but of power, and of love, and of a sound mind."
-- 2 Tim 1:7< |
|
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 30 September 2000 : 22:34:42
|
Actualy... the documentation work can go while the internationalization and CSS implimentation are going on.
Reinsnitz (Mike)
http://forum.snitz.com
reinhold@bigfoot.com
><)))'>
"For God hath not given us the spirit of fear; but of power, and of love, and of a sound mind."
-- 2 Tim 1:7< |
|
|
|
gor
Retired Admin
Netherlands
5511 Posts |
Posted - 30 September 2000 : 22:41:59
|
That is another reason why I started the discussion about it now.
Both things will take some time, but won't involve big changes as far as installing the forum, administering it or using it goes.
That means that i.e. the way the interface behaves is going to be relatively stable for a while.
Creating detailed technical documentation about how the code itself works wasn't something I wanted to start with  , because that is something that would change almost every day.
And though I know some of the professional programmer out there will disaggree, for me this code is its own documentation.
Pierre Gorissen
Experience is that marvelous thing
that enables you to recognize a mistake when you make it again.
F.P.Jones< |
|
|
|
gor
Retired Admin
Netherlands
5511 Posts |
Posted - 01 October 2000 : 00:28:17
|
quote:
I agree that documentation should be a major push right now. I have done a lot of techinical writting for satellites but have never delved into XML, yet
3. Don't reinvent the wheel. I'm sure that there are systems or scripts already out there that will do the job without having to write something new. A slightly modified version of this forum (without all the bells and whistles) might even work.
One of the thing I was thinking of was something like the The GNOME Handbook of Writing Software Documentation or Opendoc
But those only have editors and compilers for Linux.
Pierre Gorissen
Experience is that marvelous thing
that enables you to recognize a mistake when you make it again.
F.P.Jones< |
|
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 02 October 2000 : 09:42:27
|
Sue has done some documenting in her day too... maby she would have a good suggestion?
Reinsnitz (Mike)
http://forum.snitz.com
reinhold@bigfoot.com
><)))'>
"For God hath not given us the spirit of fear; but of power, and of love, and of a sound mind."
-- 2 Tim 1:7< |
|
|
|
davemaxwell
Access 2000 Support Moderator
USA
3020 Posts |
Posted - 02 October 2000 : 10:18:06
|
quote:
That means that i.e. the way the interface behaves is going to be relatively stable for a while.
Creating detailed technical documentation about how the code itself works wasn't something I wanted to start with , because that is something that would change almost every day.
I don't think we need to go into detailed technical documentation because that would require major changes to the documentation every time a new feature is added. Besides, like you said, it is pretty straight forward (though the inc_functions could use some simplifying/documentation)
I would suggest we "assign" people a specific function (adding a category/forum, admin functions, moderating, basic use, etc) and let them document each feature. One person should then be responsible for style, consistency issues (I would agree with Mike the Sue would be the most qualified to coordinate this effort) and organize the documentation.
Dave Maxwell
--------------
When's the next meeting of Snitzaholics Anonymous < |
|
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 02 October 2000 : 10:30:28
|
one step further... One person should write a couple sections of Documentation... and publish it to the Documentation group as as standard for style and format... and then take the role of compiler/QA... that way there should be a lot less re-work.
Reinsnitz (Mike)
http://forum.snitz.com
reinhold@bigfoot.com
><)))'>
"For God hath not given us the spirit of fear; but of power, and of love, and of a sound mind."
-- 2 Tim 1:7< |
|
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 02 October 2000 : 12:40:01
|
I guess something else I'll do while everyone is doing documentation... is start documenting the code better too
a friend of mine here told me about a company policy here (I just found out about it after a year and a half) of puting a boiler plate at the begining of every file, with a change history and information about the file and what it interacts with... and do the same for each function and what globala variables it interacts with... so I'll be working on this for about a month... hehe
however, I will release the internationalized version before that is done.
Reinsnitz (Mike)
http://forum.snitz.com
reinhold@bigfoot.com
><)))'>
"For God hath not given us the spirit of fear; but of power, and of love, and of a sound mind."
-- 2 Tim 1:7< |
|
|
|
John
Junior Member
USA
427 Posts |
Posted - 03 October 2000 : 12:33:25
|
quote:
3. Don't reinvent the wheel. I'm sure that there are systems or scripts already out there that will do the job without having to write something new. A slightly modified version of this forum (without all the bells and whistles) might even work.
*raises hand*
Infopop (ubb company) did something like that (http://infopopfaq.infopop.net), they use a customized version of OpenTopic (enterprise, hosted ubb sorta) for their faq page thing. We could just use a customized snitz forums at like http://forum.snitz.com/docs for the documentation. I'll even do it if u want... (I like doing that kind of thing  )
John Miller
For I am not ashamed of the gospel, for it is the power of God for salvation to everyone who believes
Romans 1:16< |
|
|
|
gor
Retired Admin
Netherlands
5511 Posts |
Posted - 03 October 2000 : 13:49:26
|
hmm, I took a look at the UBB link.
For online use that is good, but I always want to be able to print out documentation and be able to read it online.
Like i.e. the MySql documentation.
Or didn't I look close enough at the UBB thing ?
Pierre Gorissen
A man who is 'of sound mind'
is one who keeps the inner madman under lock and key.
Paul Valery< |
|
|
|
heptite
Average Member
USA
547 Posts |
Posted - 03 October 2000 : 17:15:41
|
quote:
hmm, I took a look at the UBB link.
For online use that is good, but I always want to be able to print out documentation and be able to read it online.
Like i.e. the MySql documentation.
Or didn't I look close enough at the UBB thing ?
Pierre Gorissen
A man who is 'of sound mind'
is one who keeps the inner madman under lock and key.
Paul Valery
We need:
Online documentation
Printable documentation
.pdf documentation
Documentation for users and admins, and moderators. Plus clear setup documentation. The setup stuff is going to be the most used in the beginning.
Sue
ASPDiva Forum - http://www.aspdiva.com/forum/default.asp
< |
|
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 03 October 2000 : 21:51:01
|
something else to consider here is this...
in the past it was needed to distribute .PDF format, however, with the wide distribution of "Star Office", we can now prety comfortably release .DOC... and of course... a .HTM version.
thoughts?
Reinsnitz (Mike)
http://forum.snitz.com
reinhold@bigfoot.com
><)))'>
"For God hath not given us the spirit of fear; but of power, and of love, and of a sound mind."
-- 2 Tim 1:7< |
|
|
|
John
Junior Member
USA
427 Posts |
Posted - 03 October 2000 : 21:52:20
|
quote:
hmm, I took a look at the UBB link.
For online use that is good, but I always want to be able to print out documentation and be able to read it online.
I don't quite get what you're saying... why can't you just print a webpage?
As for .pdf docs, is that really needed?
John Miller
For I am not ashamed of the gospel, for it is the power of God for salvation to everyone who believes
Romans 1:16< |
|
|
|
gor
Retired Admin
Netherlands
5511 Posts |
Posted - 04 October 2000 : 01:26:44
|
quote:
I don't quite get what you're saying... why can't you just print a webpage?
As for .pdf docs, is that really needed?
As far as I could see at the UBB site, to get a full manual I had to print a lot of different pages.
If i.e. the manual becomes huge (like the MySql with its 700 pages) printing webpages isn't an option. You would want page-numbers and a table of contents, an indexlist etc to go with it.
PDF is nice to have, and might be even easier to build then DOC.
But anyway if we are doing manual build, I've got a legal copy of Adobe Acrobat so I could do the conversion from DOC -> PDF without a problem.
Pierre Gorissen
A man who is 'of sound mind'
is one who keeps the inner madman under lock and key.
Paul Valery< |
|
|
|
Topic |
|
Forum Locked
