Help me test a Calibre help file?

BeccaPrice · 06-20-2012, 10:44 PM

I'm taking a class where we're learning how to use a specific help authoring tool (called a HAT). Using comments from an earlier thread here, and other resources, I've put together a very basic help file on using calibre, plus included some of the tips I've gathered for my own use.

Please note, this file doesn't pretend to be a complete guide to using calibre - the intent of the class isn't to document something so much as it is to learn how to use the HAT.

Could you take a minute or two and look at this site and tell me what you think? While I know that content isn't that important for the class, I'm a content kind of girl, and I hope that my information is, at least, accurate.

(note: I know the site will be slow to load - the student servers are not very bright, I think.)

It's only an alpha draft, and I've already found some things that should work that don't (in the About Calibre topic, there's a sound file that *should* play and doesn't seem to in the compiled version). I haven't indexed it yet (that's a task for tomorrow) either.

I will really appreciate any comments and suggestions anyone may care to give me.

Thanks!

Cdesja5 · 06-20-2012, 11:05 PM

I haven't gone through it all, read to the metadata section and I think that it would be very helpful to anyone who actually took the time to read it through... Particularly for a new user. You've obviously put a lot of work into this!

BeccaPrice · 06-21-2012, 09:03 AM

Thanks! (if I don't document what I learn, I've discovered that I forget what I did and why I did it, so a lot of this is based on my own notes to myself!)

theducks · 06-21-2012, 10:25 AM

I am jumping around in your Help here, so don't expect any orderly notes

Observations (I use Firefox 12 if that matters

)

Main Page: I clicked on the blue Metadata in the middle of the page (I saw a change) I had to click cycle a couple of times to figure out what changed. I don't think adding an inline expansion in the same style is obvious enough

(And you thought you were going to get a Calibre critique

)

About the Calibre Library:

(wording nit pick)

Code:

Caution: Do NOT change the calibre library structure. 
calibre is a database, Files and folders are part of the Database.
Any changes to the library file or folder namestructure will break the database, and calibre won't be able to find your books.

(nit as this applies to a GUI user)

Code:

When calibre converts a file, it creates a new folder in the directory that you specified when you set up calibre with the welcome wizard.

When you add a book, Calibre creates a folder for the book inside the Author folder. If the Author folder does not exist, it will be created.
Any conversions on that book, will be placed or replaced within that folder.

FYI

Code:

 C:\Users\xxxx\MyDocuments\Calibre Library\author name\book name (calibre DB index number)

. The Index number is what ties this folder to a particular (version of the) book listing in the Calibre.

(nother nit) Metadata A backup of the metadata

on 'About Calibre: '

Click here for to hear the proper pronunciation of calibre.
(do you have a speaker/sound icon that could be used instead of 'here'.

I have run out of comment steam and time..

BeccaPrice · 06-21-2012, 10:38 AM

all good wording changes - thanks.

I've been thinking about finding a speaker icon to use instead of "here" but only if I can get the sound effect working.

morantis · 06-21-2012, 10:39 AM

Is there a background markup that Google Chrome could be getting an error on?

BeccaPrice · 06-21-2012, 10:48 AM

theducks @ #4

Quote:

Main Page: I clicked on the blue Metadata in the middle of the page (I saw a change) I had to click cycle a couple of times to figure out what changed. I don't think adding an inline expansion in the same style is obvious enough

unfortunately, that's the default for the program I'm using to develop Help with, and I don't have any control over how glossary expansions look.

BeccaPrice · 06-21-2012, 10:49 AM

Quote:

Originally Posted by morantis

Is there a background markup that Google Chrome could be getting an error on?

do you mean you're trying to look at it in Chrome and are getting an error message? If so, what is the error message - I'll see if my instructor can help me figure out why it won't run in Chrome.

-becca

theducks · 06-21-2012, 11:24 AM

Quote:

Originally Posted by BeccaPrice

theducks @ #4

unfortunately, that's the default for the program I'm using to develop Help with, and I don't have any control over how glossary expansions look.

Yech!

A Balloon would be better than that (not even a background change, or drop down)
Note: Theducks come from an era where software came with a stack of printed manuals (hardware?

) and the Glossary was at the back.

BeccaPrice · 06-21-2012, 11:29 AM

I'm going to talk to my teacher about using popups rather than expanding text for the glossary. Like you, I don't find that expanding text very usable.

unboggling · 06-21-2012, 01:12 PM

I like that your help file is geared toward very new users to calibre. You keep it simple and non-technical, so I think it would help rather than confuse them. The topics flow congruently with the natural progression of learning that new calibre users experience. This reminds me of Apple Help files on a Mac, which is a good thing, and surprisingly difficult to write.

BeccaPrice · 06-21-2012, 04:51 PM

could someone test the files on a mac and on linux?

also, what are the defaullt library paths for installation on OS X and Linux? I'd like this thing to be as cross-platform compliant as I can make it.

Polarpenguin · 06-21-2012, 05:00 PM

It's working for me in Chrome
@ morantis do you have any add-ons installed that maybe blocking it?

@ Becca As others, I haven't looked through everything but random topics & I like it. Very simple & easy to understand, which is great for new users.

I did notice in Tweaks > Adding Series Information to the Book Title you say that plugboards only affect Kindles. Plugboards can be used on any device.
edit: Just seen your question regarding that in other thread.

Great Job

BeccaPrice · 06-21-2012, 05:07 PM

Yeah - my notes were wrong about the tweaks bit, and I've fixed that.

can some one give me a better definition of "tweaks" than what I've got? it seems pretty anemic. (I suppose I've included some things in that section that aren't strictly speaking tweaks - is there a better word for that sort of rag-tag collection of neat things you can do?)

theducks · 06-21-2012, 06:01 PM

Quote:

Originally Posted by BeccaPrice

could someone test the files on a mac and on linux?

also, what are the defaullt library paths for installation on OS X and Linux? I'd like this thing to be as cross-platform compliant as I can make it.

Your path is correct.
The issue is different versions of windows have different Absolute Paths.

The default is located in %HOMEPATH% (The home of 'My Documents' folder , Favorites...) (and yes, you can use %homepath% at the command prompt.

To see your Homepath, type set<enter> at the command prompt

In Linux it is in the users Home folder /Home/<username>
To see the Home dir type export <enter> at the terminal prompt

06-20-2012, 10:44 PM	#1
BeccaPrice Wizard Posts: 2,146 Karma: 11174187 Join Date: Jan 2011 Device: Sony 350, K3-3G, K4SO, KPW	Help me test a Calibre help file? I'm taking a class where we're learning how to use a specific help authoring tool (called a HAT). Using comments from an earlier thread here, and other resources, I've put together a very basic help file on using calibre, plus included some of the tips I've gathered for my own use. Please note, this file doesn't pretend to be a complete guide to using calibre - the intent of the class isn't to document something so much as it is to learn how to use the HAT. Could you take a minute or two and look at this site and tell me what you think? While I know that content isn't that important for the class, I'm a content kind of girl, and I hope that my information is, at least, accurate. (note: I know the site will be slow to load - the student servers are not very bright, I think.) It's only an alpha draft, and I've already found some things that should work that don't (in the About Calibre topic, there's a sound file that should play and doesn't seem to in the compiled version). I haven't indexed it yet (that's a task for tomorrow) either. I will really appreciate any comments and suggestions anyone may care to give me. Thanks!

06-21-2012, 05:00 PM	#13
Polarpenguin Groupie Posts: 176 Karma: 1834850 Join Date: May 2011 Location: UK Device: Sony PRS-300, Sony PRS- T3S, Kobo aura H2O Kobo aura One Kobo libra	It's working for me in Chrome @ morantis do you have any add-ons installed that maybe blocking it? @ Becca As others, I haven't looked through everything but random topics & I like it. Very simple & easy to understand, which is great for new users. I did notice in Tweaks > Adding Series Information to the Book Title you say that plugboards only affect Kindles. Plugboards can be used on any device. edit: Just seen your question regarding that in other thread. Great Job Last edited by Polarpenguin; 06-21-2012 at 05:03 PM.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Test for Calibre open on another computer	chrisparker	Calibre	3	01-11-2012 05:12 AM
Windows batch file to test, debug and develop recipes	euleralves	Recipes	8	04-01-2011 04:22 PM
Can someone test this prc file for me?	bthoven	Ectaco jetBook	2	10-08-2009 09:51 PM
Would someone kindly test the attached file, using a mac and a kindle?	anthonymoody	Amazon Kindle	22	02-09-2009 04:42 PM
Very Short pdf file test.	harpum	iRex	0	01-20-2007 11:44 PM

06-20-2012, 11:05 PM	#2
Cdesja5 Wizard Posts: 1,117 Karma: 2094306 Join Date: Oct 2011 Location: Montreal, Canada Device: Lots and lots of electronic gadgets...	I haven't gone through it all, read to the metadata section and I think that it would be very helpful to anyone who actually took the time to read it through... Particularly for a new user. You've obviously put a lot of work into this!

06-21-2012, 09:03 AM	#3
BeccaPrice Wizard Posts: 2,146 Karma: 11174187 Join Date: Jan 2011 Device: Sony 350, K3-3G, K4SO, KPW	Thanks! (if I don't document what I learn, I've discovered that I forget what I did and why I did it, so a lot of this is based on my own notes to myself!)

06-21-2012, 10:25 AM	#4
theducks Well trained by Cats Posts: 31,047 Karma: 60358908 Join Date: Aug 2009 Location: The Central Coast of California Device: Kobo Libra2,Kobo Aura2v1, K4NT(Fixed: New Bat.), Galaxy Tab A	I am jumping around in your Help here, so don't expect any orderly notes Observations (I use Firefox 12 if that matters ) Main Page: I clicked on the blue Metadata in the middle of the page (I saw a change) I had to click cycle a couple of times to figure out what changed. I don't think adding an inline expansion in the same style is obvious enough (And you thought you were going to get a Calibre critique ) About the Calibre Library: (wording nit pick) Code: Caution: Do NOT change the calibre library structure. calibre is a database, Files and folders are part of the Database. Any changes to the library file or folder namestructure will break the database, and calibre won't be able to find your books. (nit as this applies to a GUI user) Code: When calibre converts a file, it creates a new folder in the directory that you specified when you set up calibre with the welcome wizard. When you add a book, Calibre creates a folder for the book inside the Author folder. If the Author folder does not exist, it will be created. Any conversions on that book, will be placed or replaced within that folder. FYI Code: C:\Users\xxxx\MyDocuments\Calibre Library\author name\book name (calibre DB index number) . The Index number is what ties this folder to a particular (version of the) book listing in the Calibre. (nother nit) Metadata A backup of the metadata on 'About Calibre: ' Click here for to hear the proper pronunciation of calibre. (do you have a speaker/sound icon that could be used instead of 'here'. I have run out of comment steam and time..

06-21-2012, 10:38 AM	#5
BeccaPrice Wizard Posts: 2,146 Karma: 11174187 Join Date: Jan 2011 Device: Sony 350, K3-3G, K4SO, KPW	all good wording changes - thanks. I've been thinking about finding a speaker icon to use instead of "here" but only if I can get the sound effect working.

06-21-2012, 10:39 AM	#6
morantis Zealot Posts: 125 Karma: 769546 Join Date: May 2012 Device: none	Is there a background markup that Google Chrome could be getting an error on?

06-21-2012, 11:29 AM	#10
BeccaPrice Wizard Posts: 2,146 Karma: 11174187 Join Date: Jan 2011 Device: Sony 350, K3-3G, K4SO, KPW	I'm going to talk to my teacher about using popups rather than expanding text for the glossary. Like you, I don't find that expanding text very usable.

06-21-2012, 01:12 PM	#11
unboggling Wizard Posts: 1,065 Karma: 858115 Join Date: Jan 2011 Device: Kobo Clara, Kindle Paperwhite 10	I like that your help file is geared toward very new users to calibre. You keep it simple and non-technical, so I think it would help rather than confuse them. The topics flow congruently with the natural progression of learning that new calibre users experience. This reminds me of Apple Help files on a Mac, which is a good thing, and surprisingly difficult to write.

06-21-2012, 04:51 PM	#12
BeccaPrice Wizard Posts: 2,146 Karma: 11174187 Join Date: Jan 2011 Device: Sony 350, K3-3G, K4SO, KPW	could someone test the files on a mac and on linux? also, what are the defaullt library paths for installation on OS X and Linux? I'd like this thing to be as cross-platform compliant as I can make it.

06-21-2012, 05:07 PM	#14
BeccaPrice Wizard Posts: 2,146 Karma: 11174187 Join Date: Jan 2011 Device: Sony 350, K3-3G, K4SO, KPW	Yeah - my notes were wrong about the tweaks bit, and I've fixed that. can some one give me a better definition of "tweaks" than what I've got? it seems pretty anemic. (I suppose I've included some things in that section that aren't strictly speaking tweaks - is there a better word for that sort of rag-tag collection of neat things you can do?)

Advert

Advert