| Author |
 Topic  |
|
blkrogue
New Member
USA
79 Posts |
 Posted - 04 October 2000 : 05:19:34
|
*babbling mode on*
Hmmm, dunno much about writing documents, but been building a help file here at work for a dll we've written and that's easy to do ........ just write html-files, combine them to a nice help-file structure with HTML Help Workshop (downloaded from microsoft) and you've got yourself a nice help file to support your product (and with all the html files, you got yourself an online version as well if you build a nice index page/frames setup mdsn style) ....... can anyone tell me whether or not a help file can be converted to pdf or is it able to convert a html site to a pdf format? .......... if so I guess you can also provide a printable download pdf thingie ....... or something like that.
*babbling mode off*
Blkrogue
In the darkness of my soul a sparkling light has appeared< |
 |
|
|
Da_Stimulator
DEV Team Forum Moderator
USA
3373 Posts |
Posted - 08 October 2000 : 05:19:20
|
I personally would write it in ASP. Create one master file, default.asp, then go from there.
In the main default.asp something like the following
--------------------
<% pageid = request("page")
title = "Snitz Documentation"
%>
<%
if pageid = "admin" then pagetitle = "Admin Functions" end if
if pageid = "mod" then pagetitle = "Mod Functions" end if
%>
<-- Header file, for template
<% if pageid = "admin" then %>
<-- File containing the docs
<% end if %>
<% if pageid = "mod" then %>
<% end if %>
<-- footer file
-------------------
etc etc
Then in the admin.txt or mod.txt you would put all the documentation regarding that area. example...
<% =pagetitle %>
BLAH BLAH BLAH BLAH
-----------------
In the top.txt would be something like this
<% =title & response.write("|") & =pagetitle %>
Administrative Functions | Moderator Functions
-----------------------
Bottom.txt would simply be unless you include more of a footer.
Calling the script would be like default.asp?page=admin for admin functions etc etc default.asp?page=toc table of contents, that way its all in one file, so you can easily add another page without too much coding.
-- http://aokingdom.com -- head webmaster/creator
-- He who has never made a mistake, has never made a discovery --
Edited by - da_stimulator on 08 October 2000 05:22:58< |
|
|
|
Sabre Cat
New Member
USA
55 Posts |
Posted - 18 October 2000 : 14:21:25
|
How about this.
I'm thinking about this... Thinking... Thinking... Yes. Okay. We break it down like this:
A) Administration FAQ/How To
A.2) Set up (All the really technical knowlage. Things like how to install your database, determining if your server supports what you need to run Snitz, and what E-mail setup to use)
A.3) Customization (Setting up Look and Feel)
A.4) Day-to-Day management (Adding New forums, deleting old ones, things of that nature)
A.5) Adding User Mods (Basic instructions for adding new code)
A.6) Upgrading (Updated every time we put forth a new version. Including instructions for upgrading up to 2 versions back. Archived so you can look up past upgrades)
A.7) Version History (Just what it sounds like. A COMPLETE feature list of EVERY version)
A.8) Managing your Users (Add/Delete/Modify/Lock)
B) User-Side FAQ
B.2) Registering
B.3) Posting
B.4) Editing your posts
B.5) Changing your User Information
B.6) Sending users messagages through ICQ/AIM/Yahoo/Ectera
C) So you want to start a mod...
C.2) How to get the source code
C.3) Rules for modding (Your mod belongs to Snitz)
C.4) How to make your mod known
C.5) Basic file list (Breakdown of what each file does)
--------------------
I can probably write everything except for C.4, C.5, and parts of A.2 and A.5.
Thoughts? Comments? I'm anxious to get started, and I would hate to see the Programmers wasting their time away writing all the really boring, repetitive, "Newbie-targetted" type of stuff... When their time could be much better spent hunting down bugs so we can start ot intergrate some of the killer mods out there!
I'm thinking that we could write each page seperately, and then use a lil' ASP to make a file where you could select which sections you want to view, and it would display them in a printable format.
I don't really know why a PDF file is needed, honestly... My own experience is that it's good to keep your documentation in one place, in one format - otherwise updating the content becomes a such a chore that NO ONE wants to do it!
Besides which, everyone knows how to use a broswer to view HTML... But there are some poor SOBs stuck in the stone age without something to view PDF, and scared at the idea of having to install a new program. (It's true!).
A doc file may work, though... EVERYONE has some form of word.
< |
|
|
|
gor
Retired Admin
Netherlands
5511 Posts |
Posted - 18 October 2000 : 14:36:28
|
The list looks good to me 
I have some questions on the technical side though.
quote:
I'm thinking that we could write each page seperately, and then use a lil' ASP to make a file where you could select which sections you want to view, and it would display them in a printable format.
That sounds ok to me, am I making it to complex by thinking we should have some default format to make sure we don't get 10 different kind of layouts etc ?
That was what I was thinking of when I mentioned the GNOME project. Though I do aggree that might be a bit of an overkill. Maybe a subset of this ?
quote:
I don't really know why a PDF file is needed, honestly... My own experience is that it's good to keep your documentation in one place, in one format - otherwise updating the content becomes a such a chore that NO ONE wants to do it!
Besides which, everyone knows how to use a broswer to view HTML... But there are some poor SOBs stuck in the stone age without something to view PDF, and scared at the idea of having to install a new program. (It's true!).
A doc file may work, though... EVERYONE has some form of word.
Ehm I am one of those SOBs that like a PDF  . I also don't really think it is harder to create than a Word document.
Do you know a way to build the complete Word document with ASP or were you just going to import the pages one by one ?
Pierre Gorissen
Maturity is only a short break in adolescence.
Jules Feiffer< |
|
|
|
Sabre Cat
New Member
USA
55 Posts |
Posted - 18 October 2000 : 15:56:19
|
Gor, =)
No, we definately need some standard layout patterns! I've got some ideas floating around in my head, but in general, I'm thinking we need a method of displaying a large amount of content in an easy-to-read manner.
The ASP idea was just one of many. It's also not something that I could do on my own... <=(
With the word document... Yes, imported page at a time. Again, however, this would be a slow-down. Which is why I say "Do we absolutely NEED a word or PDF file? What would it gain? What would it cause us in the way of pain?"
Gains:
A) It may look a bit prettier than HTML
B) Help me out here?
Taxes:
A) More files to update... slower updates, more administrative confusion and frustration
B) We'd have to maintain a downloadable file... which isn't too hard, I suppose
< |
|
|
|
HuwR
Forum Admin
United Kingdom
20584 Posts |
Posted - 18 October 2000 : 17:11:39
|
quote:
I guess something else I'll do while everyone is doing documentation... is start documenting the code better too
I don't mind volunteering to ducument some of the code, I'm not good at manuals, but understand code well enough to add the odd comment or two and make it more readable.
'Resistance is futile'< |
|
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 18 October 2000 : 21:04:44
|
:) WOO HOO Go Team!
Reinsnitz (Mike)
><)))'>
Trust in the Lord with all your heart and lean not on your own understanding; in all your ways acknowledge him, and he will make your path straight.
-- Proverbs 3:5-6< |
|
|
|
Da_Stimulator
DEV Team Forum Moderator
USA
3373 Posts |
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 24 October 2000 : 15:29:23
|
I think this would be a good Database App maby?
put all the text in a db... write a simple presentation app... this could be done in MS Access... and distributed with the forums? Or even be used to write text docs... either way... your talking a lot of manual work, or a similar amount of time writing the applicatiion that will do most of the work for you in every revision.
Reinsnitz (Mike)
><)))'>
"I no longer call you servants, because a servant does not know his master's business. Instead I have called you friends..."
-- John 15:15< |
|
|
|
HuwR
Forum Admin
United Kingdom
20584 Posts |
Posted - 24 October 2000 : 16:03:10
|
I agree, putting the text in a db and then using ASP/application to view offline. although putting it in a DB would be limited to specific operating systems.
'Resistance is futile'< |
|
|
|
davemaxwell
Access 2000 Support Moderator
USA
3020 Posts |
Posted - 25 October 2000 : 08:21:44
|
quote:
although putting it in a DB would be limited to specific operating systems.
If I understand Mike's idea, it would be an online type of manual, which the user would add to their site similar to the way the forum is implemented. That way, if they can run the forum, they can run the documentation.
Dave Maxwell
--------------
When's the next meeting of Snitzaholics Anonymous < |
|
|
|
André
Starting Member
24 Posts |
Posted - 20 December 2000 : 10:13:12
|
Well if i may suggest why not just a simple
word file then placed in html file, which would be easier to correct and add on etc.
You would not have to deal with asp code inside the document!
Just a suggestion
< |
|
|
|
KoRnholio
Starting Member
30 Posts |
Posted - 23 December 2000 : 23:20:11
|
I may seem old-fashioned, but why not just do this in .txt form? It is by far the easiest, and there are several programs available that can port that to several different formats. Especially to HTML. Documentation doesn't have to be pretty, and with the possible huge filesizes, the most space-efficient format would work for displaying the greatest amount of information in the least amount of disk space. I, for one, have a 28.8 modem, so of course I would want a .txt manual :)
< |
|
|
|
Topic |
|
Forum Locked
