RE: Re: HTML Help

> I also don't want to focus on CVS operations themself. I think we can 
> utilize the fact that CVSNT now comes with it's own help file 
> and just link to that or even the webpage.

Well, yes but it's basically still the same old Cederqvist with some 
CVSNT enhancements added that has already been intimidating novice users 
for ages... anyway, this touches another issue I already had on my 
todo-list ever since I started documenting the current GUI: 

I think the GUI could do with a concerted effort to make captions, 
labels and hint texts: A. consistent throughout all dialogs and menus 
(e.g. there are at least three different captions for "do not recurse" 
options) and B. consistent with the corresponding descriptions of 
options in the commandline client (i.e. cvs -H output) where applicable. 
The latter would be even more important if you were planning to simply 
link the dialogs to the CVSNT manual.


> I don't want to make a screenshots of each dialog and explain all the 
> options one by one because there is a much better and simpler way to 
> do this - help popups activated by a "?" button on the title bar of 
> each dialogs. A couple of lines of text can easily explain what each 
> option does.

There's only so much information you could put into those popups. I see 
the strength of a full-blown help file here in being able to inject 
notes, hints and tips and cross-links to related topics, e.g. notes 
about common mistakes or alternative ways of doing something.

In any case I definitely have troubles imagining how you would be able 
to pull anything useful out of the documents I created so far if that is 
what you're after... well, the option descriptions _are_ there but they 
only make up a tiny fraction of what I'm doing or about to do...

I just don't want to put all that effort into producing a full-blown 
XHTML-compliant documentation project with Glossary, Index, Related 
topics links, Basic Concepts chapters and nice stylesheets if all that's 
going to happen to it in the end is that individual option description 
texts get copy&pasted into tiny popups... now I know this is not what 
you have in mind but I think you get the point of my concern. I wanted 
to produce something that novice users would not just clap shut again 
right after having taken a quick look at it as I think is the case with 
most CVS documentation currently out there...


> User doesn't have to and doesn't want to see the 
> screenshots in the help files because he can simply see the real 
> thing, the dialog itself.

In fact that's contrary to our observations, even though I must admit 
that these observations probably do not apply to the majority of 
developers. We're targetting a far less tech-savvy audience. Problem is 
most of those people are uncomfortable with having multiple windows 
visible at the same time (in this case the application and the help 
file). Personally, whenever I have to work on a single monitor setup 
below 19" I tend to feel the same. Clickable screenshots inside the help 
files IMO put all the information readily available back in one neatly 
organized window...


> Instead, the dialog's help, as I see it, 
> explains in generic terms as to what the dialog is doing, some tricks 
> and FAQs. 

OK, that's a lot closer to what I have been doing. Definitely the road 
to consensus... ;)


> I also want to have a simple, one-to-one mapping for dialog's help 
> files. It really helps when it comes to updating and maintaining the 
> files afterwards. 

Depends. Maybe I'm misunderstanding you but if you mean that each 
helpfile should be self-contained, i.e. without any cross-links that 
could potentially become invalid, this would mean you have to explain 
things like the Module or Tag browser or CVSROOT wizard or history 
combos or the semantics of revision identifiers or modules, just to name 
a few, all over again for each and every dialog that uses them. That is 
an awful lot of duplicated content that has to be kept in sync... I 
prefer just keeping the links valid. It's easy to do with the right 
tools.


> > I simply associated each dialog with an explicit URL (in contrast 
> > to something auto-generated from the dialog resources or whatever) 
> > inside the help file and each control on those dialogs worthy of 
> > documentation with an anchor inside that associated file (still 
> > allowing an individual override for links to other URLs as well). 
> 
> This is the same thing. In the HTML project file you create aliases 
> that link to whatever location in the help.

Ah, OK. I wasn't aware of aliasing so far. Will have a look at it.


> The auto-generated part 
> just makes job easier because it allows to use symbolic names simliar 
> to the ones used in the code for that mapping. The files function 
> should be obvious from the name while the mapping makes it 
> clear where the files are used.

OK. I'll have a deeper look into the implementation then. Didn't have 
much time for it so far. Will probably have to wait until next week...

 
> I am not sure what you mean by "override" here...?

In our case I associated every dialog with exactly one topic file inside 
the help file. Control help by default only links to anchors inside that 
very document. Sometimes however it is necessary to link to (an anchor 
in) a different document, e.g. because it is a common control that is 
used on a lot of other dialogs or simply because the explanation in 
question is too verbose to include in the main file for that dialog. I 
needed to make sure that that was still possible.


> You can still create documentation separately, e.g. the 
> writer doesn't 
> care where I link his files from. But it helps to keep documentation 
> close to the software structure, particularly in our case.

I think I am fulfilling at least that requirement with what I've been 
doing so far. Just not to the point where I actually named files and 
anchors after identifiers used in the code. You could probably say, I am 
currently keeping close to the "outside" structure of the software.


> What about the .hhp and other project files?

Actually they are already there if you know where to look. They're right 
next to the .chm file with corresponding .hhp/.hhc/.hhk extensions.


> Can you zip all files as 
> they are and upload that too?

Will probably do that tonight.

Cheers,

Oliver
----	------------------
JID:	[email protected]
ICQ:	18777742	(http://wwp.icq.com/18777742)



------------------------ Yahoo! Groups Sponsor --------------------~--> 
Yahoo! Domains - Claim yours for only $14.70
http://us.click.yahoo.com/Z1wmxD/DREIAA/yQLSAA/NhFolB/TM
--------------------------------------------------------------------~-> 

 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
     http://groups.yahoo.com/group/cvsgui-dev/

<*> To unsubscribe from this group, send an email to:
     [email protected]

<*> Your use of Yahoo! Groups is subject to:
     http://docs.yahoo.com/info/terms/