dungeon craft update!

[Ziroc]

Originally posted by manikus: i think documentation for dc would be great. [img]smile.gif[/img] i personally prefer .pdf b/c it is so versatile, but i own adobe pagemaker and distiller. i think you paul makes some very excellent arguments for using another format, i think we should be as easy to access for anyone that wants to help, and open source, to be read as free, is certainly easier to access than adobe, to be read as expensive. i have cheetah 8 i think, and it's really quite easy to use. there's always html as well. honestly, there's no reason why it can't be all of the above. and it probably wouldn't hurt to have a .txt version sans the pictures for those of us still using dial-up. some individual points- ziroc- readme files or tutorials? i think it's very different to have a file that says what a function does, and to have a file that walks someone through making an item or monster. i think both are very valuable, depending on what you want to get out out of the program. -manikus

Duh! I didn't even THINK of html. lol. (bonk) I think that would be the best and most compatible way to do the manual. Then we can have a text file (Readme) with no pics for the low bandwidth folks, and have a separate *maybe?* manual for tutorials.. Ideas?

[Paul Stevens]

I almost suggested HTML. But I am so ignorant of available
tools, etc. that I thought it best to keep my mouth shut (so
to speak). Here are some very uninformed questions:

DC documentation is going to be a LARGE project. It will
consist, I am sure, of several THOUSAND files. And, to be
useful, those files will reference one another. And
several thousand files referencing one another will be
very much like the worst 'spaghetti-code' that has been
created by assembly-language programmers. I spent many
years struggling with such code.

1)So how can it be organized? Have you thought about it?
2)Are there tools to help organize HTML as a Help Document?
For example, you would have to have a 'cross-reference' tool.
3)Are you prepared to spend a couple of months outining the
shape of the documentation? This involves DOCUMENTING the
documentation project, sharing that with peers, and accepting
feedback. Without such preparation you are surely doomed.
4)Are you prepared not just to spend time doing this but
WORKING at it? Ask CocoaSpud. He is doing his part
out of love for the project but it is often hard work and
really no fun at all.
5)Can you accept help from others without second-guessing
everything they might do? This is going to be more than
one person can reasonably do. (another reason for a good
plan or outline so that parts can be delegated)

I am certainly not suggesting that you are going to come up
short on any of these issues. I just want you to think
twice before committing yourself to something you think will
be easy and then feeling the pain of failure.

[Tarlanon]

Here is my $.02....

First off, I don't like the idea of an HTML doc as the primary help text. Portability is great yes, but I don't fancy the idea of having to have a big, clunky web browser open whilst I am working on my design. Already I have the editor, some running copy of the engine, my paint program, sound utils, etc. etc. open. And speaking of portability, what does it need to be portable for? Right now, DC only runs on Windows (but in the future, other OS ports would be good for the project overall). Plus from my own limited experience in working with HTML, doing multi-paned indexes is quite complex (and it would have to have a seperate index and help text pages to be truely useful). In my opinion, going to HTML, at least initally, is not the right thing to do. But that is just my opinion. -Flame Shields up!- [img]graemlins/firedevil.gif[/img]

That being said, I really like the windows based help doc that already ships with DC today (good Job Paul!) I use it fairly regulary. It is low impact to the system, and easy to use, although it might be difficult to code. If only it were easier to make.... -Warning! Allusion sensors activated-

.PDFs seems to be one of the best choices to address all of these concerns, but I don't know an aweful lot about how they are created. I'm not sure if there are any open source (which is the critical path I agree we should take for this) tools which can create PDFs.....Or is there..... -Allusion collision detected! Brace for impact!-

I was snooping around sourceforge this morning, and I came across this tool:

http://helpmaker.sourceforge.net/

This is an open source utility for creating, if nothing else, Windows help documents. It supports a lot of useful features, and seems to make organizing and maintaining the Windows help project much more manageable. AND, it says it can even produce PDF documents. The only things I don't like about it are a) I haven't be able to fully figure out how to create a PDF document, but I really didn't spend that much trying. And b) the help text which comewith with Helpmaker is somewhat...lacking....Which is really quite ironic.

Well, that was my $.02.

[ 11-06-2003, 12:02 PM: Message edited by: Tarlanon ]

[Paul Stevens]

Well, I can increase that to $0.04.

I agree that portability between operating systems
is unneeded. I believe that CocoaSpud originally
wanted portability but it seems to me that the hope
is all but abandoned. He may disagree!

I agree that HTML has drawbacks. It would seem to
require some kind of 'Help Shell' to make it useful
for our purposes. But this is from pretty much total
ignorance of the subject.

I have never created a PDF document and have no notion
of how well it would adapt to a Help file. I know it
makes great manuals.

An advantage of using the 'Microsoft' way is that it
can be reasonably integrated into the DC editor so that,
for example, you can get context-sensitive help. Isn't
there a little of this in the current editor?

Microsoft has abandoned the old help-file format. They
now have some sort of browser-based help. I have no
idea what it is, how it works, or whether it is reasonable
for amatuers like ourselves. I also have no idea if the
old help file format can be integrated with the next
generation of Windows and Visual C++.

I don't think I have any cents left. (Maybe I should
rephrase that.)

[Ziroc]

All good ideas! I'll check that program out tonight Tarlanon!

I wasn't thinking about an integrated 'help' tool, I meant a manual that COULD be printed out and they you can use it like any other manual while you're working on your project.

I've written a few manuals in my time, and the number one thing you do is make a table of contents and/or a list of features you wish to cover. then we could hand out different areas to people.

But making it in HTML can be a good thing. Once the HTML Manual is done, you have all the text, and if someone wanted to integrate it, they can simply copy and paste the text. It's an idea..

One down side for using HTML for manuals is DPI. Printing at 72dpi isn't too hot, but images at 300dpi eat up 100's of meg's, so 72 dpi will do. as long as one can read the text, and see the images, it'll convey the point.

[Tarlanon]

Z,

One of the cool things about that prog I noticed was that it can (supposedly) do both. HTML and Windows help (and theoretically PDF).

As far as publishing goes, I'll go with the community, but this might be the tool we want to use to 'bring it all together'. [img]smile.gif[/img]

[manikus]

i think there are a lot of good ideas here and some very generous offers on ziroc's part. but i also think it's become a little bit cloudy, at least to me.

the way i see it, there are three things being talked about as if they are one. 1.)a help file 2.)a designer's guide 3.)readme files.
i think that ziroc was originally concerned with 2 and 3, but was careful that he was not going to try and make 1 obsolete or be ignored.
i think some of everyone's concerns are applicable to all three, but it seems that length of time, immensity of project issues apply most to 1 (but are still valid for 2 and 3).

i think the real issue is format right now. once we can agree on a file format that everyone interested can work in, we can move on to content based issues.
i know you all have been waiting to hear what i think, so here goes.
1.)unless at some point windows is not going to support the old windows help file format, and that time is soon, we should continue to do the help file in .hlp format. if helpmaker works, it sounds cool, but there is always cheetah which is quite a good program for making help files.
2.).pdf's are top of the line for manuals and guides. everyone sees the same things regardless of which browser they are using. if we can go top of the line, we should. if helpmaker can make .pdf files, it would be great. but, if we can't find an open source program, i volunteer to make them with pagemaker. (we paid a lot for this program, might as well get our money's worth.)
3.)i think the readme files should be .txt and be text only.

i think it would be nifty to have .html (con)versions of the designer's guide and help file, but they could just be something put up later so that people can get a sample of the good stuff available for download. [img]smile.gif[/img]

[img]smile.gif[/img] with all of that said, i'm ready to help, so sign me up for the committee!

-manikus

[ 11-06-2003, 09:33 PM: Message edited by: manikus ]