User Tutorial

[ChrisGreaves]

Note to would-be Editors:
(1) This is a draft document.
(2) I am immediately interested in feedback on the layout and style, especially for the functions “Date-Modified” to “Dupe”.
(3) The 4,137 words in this document have been moved over from the document of 12,000+ words that I have been working on for the past two weeks.
(4) The structure will be based on the Everything Wiki
(5) I anticipate 32 sections of Tutorials.DOC, and the functions presented here are a small part of one section “Searching” (please see foot of the document "Functions.doc")
(6) I have uploaded a working document Template.doc with my ideas of layout, styles etc.

The two documents are attached as "20230213_0516.zip"

I will do my best to respond to comments posted here, or PM, or by email to me as CPRGreaves@GMail.com.

Thanks, Chris

[therube]

Text, chm, pdf...

Some don't use .doc .

[Raindrops]

IMHO some of the fonts in the sample are too large for their purpose, and compared to surrounding text.
As a general rule, fonts at higher level of paragraph hierarchy are larger.
So, by and large, the paragraphs that are indented to the right would have progressively smaller fonts.

Also, all headings (H1, H2, H3...) should have large and bold fonts, and formatting (e.g. underline) that catches the eye.

The left indenting of the paragraphs also need to be re-aligned: The text in blue should be indented as compared to the "example..." line above.

Formatting in Everything help doc.png (40.25 KiB) Viewed 6856 times

Thirdly, assuming that you intended to format the final pdf/doc just like this sample, I have a few suggestions:
User different headers and footers for the left page and the right page.
Put together, they should show the following details:

1. The name of the manual and product (e.g. User manual)
2. Everything version number
3. Chapter name
4. Topic name (this is the first topic that appears on the page. If the page contains multiple topics, only the first one is shown).
5. Page xxx of yyy

Further, hyperlinks can be inserted in header and footers.
For example, if we click on the version number, it takes us to Help > About page on Everything website.
This page would show all release notes for that version and all previous versions.

[Raindrops]

Personally, I prefer to use much thinner margins on all sides and gutter.
In fact, assuming that this book is going to be a soft copy (epub, pdf, djvu, etc) and not a printed book, there is no need for a gutter at all.

[Raindrops]

If we use wider margins, the free space can be put to good use, to insert icons for various types of text:

• Note
• Tip
• Caution
• Example
• Code

We can also insert summary text or inset in the margin.

This makes the book look more attractive, and makes it more readable.

[ChrisGreaves]

Text, chm, pdf... Some don't use .doc .

TheRube, thanks for this comment. Not shown here, but I have been giving this thought.
I use DOC, MP3, XLS, and even if someone else used, like me, DOC, MP3, XLS, my examples and exercises would not match! "Quantities may vary"

I will use any of, perhaps, six common formats - TXT is a good example, as is PDF, and then hope that users have enough brainpower to apply MY examples to THEIR most common files. I doubt if anyone else here has an encrypted data partition assigned as T: with 202,823 objects (see? Even THAT has changed since yesterday).

My hope is that, if nothing else, someone might just try the examples/exercises one by one and gain a better understanding of the Tutorial, enough to adapt the examples and exercises.

What is a CHM when it is at home? A HELP file, is it not? I have but 23 of them on my data partition but 288 in total, so they must be fairly common, at least in older Windows installations (today I am on my Win7 machine)

I can believe that many do not use, possibly do not have DOC on their system.
In a week or two I might poll users to see what their most common file types are.

Did you have any problems when you tried to follow the examples with your preferred types of file?
Thanks again for your feedback
Chris

[ChrisGreaves]

IMHO some of the fonts in the sample are too large for their purpose, and compared to surrounding text.

Raindrops, thank you for these comments.
I agree completely; I am great believer in Styles, and my styles here are not fixed at all. Indeed I have a table-driven styles generator, so I can easily accommodate your (or anyone else's suggestions) into a table of definitions, run the macro, and Bingo! all should be improved.
I have attached a ZIPped copy of "Guide to Template Features.doc" which, towards the end, gives a sketchy idea of my styles definitions. Note that unlike the basic MSWord facility I can use multipliers to assign font sizes relative to the parent style.

Thirdly, assuming that you intended to format the final pdf/doc just like this sample, I have a few suggestions:

Again, agreed. in this first draft I wanted to show that there WERE headers and footers. Void suggested a PDF, but whatever format we settle on, it must support hyperlinks. As much as possible I want to provide quick access to the dynamic content of both the Wikis AND the forums. I am conscious that where I have drawn material from a current post, there may be follow-up material in the topic after the User Tutorial is published. (As well I want to give credit to each poster!)

How did you find the Examples and Exercises? Did you work through any of them? test-drive the hyperlinks? Too many examples? Too few? Same for Exercises?

Thanks again for commenting; all good advice and duly preserved.

I am currently generating more text in "Functions" with a tentative deadline of a more complete version next Sunday.
Cheers, Chris

[ChrisGreaves]

Personally, I prefer to use much thinner margins on all sides and gutter.
In fact, assuming that this book is going to be a soft copy (epub, pdf, djvu, etc) and not a printed book, there is no need for a gutter at all.

Hello again Raindrops.
I had not settled on a final form. I see no problem in releasing it in several versions. DOC, PDF, and since I have a web page compiler, HTML is fine by me. I don't see a big problem of different page layouts according to each target medium - it's just another piece of VBA code from my point of view.
Right now I am still at the point of "content" - are the examples and exercises easy to follow? Is there enough detail? Enough hyperlinks into online sources. I was raised to write down ideas and only then coerce them into a nice format. Indeed, that's what editors are for, isn't it.

I do not yet know the final form. I suppose I could release it as a raw document supported by a "layout" macro that users can use to customize the document for their view. Some ten years ago I wrote a support system for the self-publishing outfit in Toronto Public Library - it took your chunks of text (body, preface, foreword, CIP data, images etc) and assembled it into a book suitable for the Big White Machine AND predicted the cost based on the number of copies you ordered.
Anything is possible!

Cheers, Chris

[Raindrops]

In the last 15 years, I have created 10+ user manuals for the freeware I use and love.
(That's my humble attempt to repay the developer who so generously donated his talent, effort and time.)

Among them, I list help docs for ReNamer, LMMS and Active Presenter as the better ones.

• ReNamer has a wiki. The user can click a button to convert the latest version of the wiki into a pdf and download.
• In case of LMMS and Active Presenter, I wrote the entire manual as a odt file in LibreOffice Writer. The odt can be exported as epub and pdf.

LibreOffice can produce pdf files with all the formats we need.
It works extremely well with styles (that's its forte!)
And the pdf it generates will have full-fledged hierarchical bookmarks tree.

So you compose it once, and export it as pdf and epub with single clicks.

Both (LibreOffice and wiki) are good, efficient options.

[Raindrops]

I forgot to mention that we will need character styles to denote the following:

• menu options (e.g. Tools > Options)
• Literal string we type in an entry box
• System responses and error messages)
• Name of a window (or dialog box)
• Name of a control (the label that is attached to a check box, button, tree node, etc.)
• Built-in option in a control (e.g. yes/no, values in a drop-down list)
• Tooltip text (literal string)
• etc.

Preferably all these styles should be distinct, so that we don't have to tell the reader what it is.
He can easily infer the meaning from the style itself.

[Raindrops]

Right now I am still at the point of "content" - are the examples and exercises easy to follow? Is there enough detail? Enough hyperlinks into online sources. I was raised to write down ideas and only then coerce them into a nice format. Indeed, that's what editors are for, isn't it.

Actually the term "style" is used in two different contexts in technical documentation. So far I was describing the text styles (paragraph styles, character styles, table styles, etc.). But we haven't yet talked about the second meaning of the term "style" that means "standard writing, grammar, and punctuation conventions".

I will post a proposal in a couple of days, as this is a harder task.

[Raindrops]

I found these guides for writing style:

1. Chicago manual of styles
2. Google developer documentation style
3. MicroSoft writing style guide
4. A list apart guide
5. Mailchimp writing style guide
6. University of Oxford Style Guide (pdf)
7. Apple style guide (pdf)

[ChrisGreaves]

I forgot to mention that we will need character styles to denote the following:
Preferably all these styles should be distinct, so that we don't have to tell the reader what it is.
He can easily infer the meaning from the style itself.

Hi Raindrops. Duly noted.
By now you will have read Template.doc and seen that I do cater for character styles.
I feel that there is a danger in having too many styles - the user spends some processing time working out what each colour is.
That is why I am interested in the layout, in terms of sequence, or paragraphs that I have used, as well as the standard of examples and exercises.
In particular, with one exception, all hyperlinks lead either to a forum topic/post OR to a Wiki page.
I think that a user will either just coast through examples and exercises so that he has tested the heft of the tool, or else will be desperately in need of the function, so that he is willing to be directed to every scrap of data that might be useful.

I want the tutorial to guide the reader along a path of learning, rather than to be a complex document that he needs to work on to gain use from it.
Cheers, Chris
P.S. Have you yet run through the examples or exercises?
C

[ChrisGreaves]

So far I was describing the text styles (paragraph styles, character styles, table styles, etc.). But we haven't yet talked about the second meaning of the term "style" that means "standard writing, grammar, and punctuation conventions".

Both of these meanings are "cosmetic", and come along after the content is settled. Formatting and spell-checking text that will possibly be deleted, modified, or rewritten, is a waste of time, is it not?
You are looking at a couple of day's sample of text that will consume about twelve months of my time!
It is the manner of writing the content that should concern us at this point!
Cheers, Chris

[void]

Community Wiki added here:

https://www.voidtools.com/wiki/

Please feel free to create an account and publish your tutorial here.

Thank you for helping with the Everything documentation!

[ChrisGreaves]

Text, chm, pdf...Some don't use .doc .

Hi TheRube. After some thought and a LOT of wading around in the swamp of my own filestore, I have decided to create one or more small file sets to be used as sample data.
Files will be drawn from the recognizable extensions doc, xls, txt, chm, pdf, jpg, png, mp3 and any other reasonable extension for which a volunteer would like to offer a set.
Reasonable: NOT exe or dll.

I anticipate building various sub-trees and then PKZip-ing them so that one or more or all of the sets can be downloaded and installed.

As an example I have a ZIP file with 120 DOCuments, all but half a dozen of size <100KB, no tree structure, many similar names, suitable for testing content, duplicate or similar names.

I will make another zip file, perhaps a copy of my T:\Greaves\Products\ folders, but with only a half dozen files in each folder.
Each Zip should be around 2MB, small enough to download and park in a sandpit, with enough variety to demonstrate every feature of Everything (except, of course, Kiloton files!)

How does that sound?

Cheers, Chris

[void]

Sounds good to me.

If you would like to publish your tutorial on the wiki and need help, please let me know.

[Raindrops]

@Chris

I went through the examples. You have linked the examples to build up a narrative.
The problem with the storytelling style is that the story itself demands that all functions must to be introduced to suit its narrative.
This is like the end titles of a movie, in which all actors are listed in the order of appearance, not alphabetically or in the order of their market value.

Such a storyline-based help documentation must be read end-to-end.
It will not serve as a reference book, where the user simply looks up the function he needs.

Moreover, even if the user searches for his function, he has to read the whole story to understand the context.
(The help does not provide him a self-contained definition, explanation and illustration.)
----------
It would be an overkill to provide a collection of files so that the user can repeat the steps given in the help and get the exact same results.
IMHO the user can use the commands on his own files and perfectly understand the meaning.
----------
I'd suggest the listing of each function in the following standard format:
(I am using the date-modified function as example)

Name: '
date-modified:

Alternative names:
dm:
datemodified:

Syntax:
date-modified:<comparison operator><date>
datemodified:<comparison operator><date>
dm:<comparison operator><date>

Where-
<comparison operator> may be any of the following:
=, >=, >, <= or <

The <date> format is according to your locale settings:
dd/mm/yyyy or dd/mm/yy
yy/mm/dddd or mm/dd/yy
You can enter / or - as separators.

Effect:
Filters the search result to show only files/folders that were modified within the specified date range.

Remarks:
In case of folders, the modified date is defined as the latest change in the content of the folder.

Illustration:
*.doc date-modified:>=21/01/2023
*.doc datemodified:>=21-01-2023
*.doc dm:>=21/01/23

See also:
(list other functions that are related: either similar or opposite functionality.)
For example, date-created and date-accessed functions can be listed here. (if they exist)

[Raindrops]

All common notations can be explained in an introductory section (e.g. date formatting, comparison operators, etc.)
They need not be explained in each function.

[ChrisGreaves]

If you would like to publish your tutorial on the wiki and need help, please let me know.

I suspect that since it is in the format of User Tutorial rather than a Reference work it may not be suitable for the wiki.
I confess that I know little about building a wiki, but the tutorial promises to be massive.

The link viewtopic.php?f=12&t=12666 takes us to a page that has some sixty hyperlinks.
Now explore each of those hyperlinks down just one level, tallying the number of hyperlinks (topics) in each of those sixty levels.
How many hyperlinks have you got?
Now assign an average of two pages per hyperlink, how many pages have you got?

The Tutorial is designed to have examples and erxecises that each will serve as an introduction to a topic.

Consider our conversation in Everything seems not to notice my edit to my bookmark.
Out of that there will arrive two (or so) pages with images, just enough to guide the novice through the business of establishing a bookmark, and three methods of executing the bookmark.
That should be enough to get someone familiar enough with bookmarks to wade into the forums with a question.
As evidenced by my comment "No. The guy who is writing the tutorial hasn't got quite that far yet (grin!)" I am, in this sense, the original novice user, trying to record all the hurdles that I meet.

The pages of the tutorial are filled with hyperlinks to specific posts, specific topics, and specific Wiki pages, in the hopes that, having created and run a Bookmark (in this example), the user will know enough to understand existing (and maintained) documentation to explore further, and become an expert in Bookmarks, sufficient for their purpose.

I am working concurrently on eight sections of those sixty; I am uploading a ZIP file each Sunday. When I have completed those eight sections I will publish them as an MSWord document and the equivalent PDF file and we shall see what we shall see.

I hope that that makes sense.

If you would like to publish your tutorial on the wiki and need help, please let me know.

I don't yet need help to publish the tutorial on the wiki, but if you want to grab, say, the incomplete six-megabyte "Searching.doc" and have a whack at it, your are welcome! I will examine a Wiki with keen interest.

Cheers, Chris

[Raindrops]

I would like to make a user's manual, which first explains all product features screen-by-screen, and then explains the various use cases (applications).

This is different from the "Tutorials" approach, where each tutorial is on a particular topic, but collectively they do not follow any order.

Both the user manual and tutorials can co-exist and supplement each other.

So, I'd like to start off with the user manual while @Chris develops the tutorials.

Based on my own experience of writing 10+ user manuals, I prefer this method:

1. Start with a TOC.
2. Rearrange the topics in this TOC in a logical order (basics -> intermediate -> advanced)
3. Re-arrange the topics in a hierarchical order (Sections -> Chapters -> topics)
4. Flesh out each chapter/topic as a separate web page.
5. Link all chapters from the TOC.
6. Contributors can go on amending the TOC (add topics, merge topics, re-arrange topics, etc).
   When the TOC is amended, the pages get re-ordered, but the content of individual pages is not disturbed.

If any topic does not fit a linear narrative, I move it to the "Appendix" section.
The Appendix section is also useful to accommodate large lists.

For example, the following chapters:

• How RegEx works
• List of pre-processors commands
• List of functions
• List of command line commands

Any thoughts are welcome!

[Raindrops]

Just to illustrate the difference, here is an excellent example:

The following documents describe the same product (QGIS), but each of them is completely different structurally:
User manual (user guide)
Training manual
Tutorials

[ChrisGreaves]

Note to would-be Editors:

The User Tutorial continues apace. Work to date has produced 80 documents occupying 33 MB of disk space. 62, 906 words and just under 500 images. So many examples and exercises that I have started a document "Extracizes.doc" to make space.

The Tutorial is in three sections. The first section, {{{ RELEASED TODAY}}} corresponding to the "Quick Start" in the documentation of many applications is quite short, a mere 1,000 words. The second section (two weeks time?) should whet the appetite of anyone who is still with us after the first section. The third section (three months ? ?? ???) will, by definition, exhaust my knowledge of Everything. At that stage I fancy throwing the entire work into the public/Everything domain, because (a) I will want to get my lufe back and (b) there are features of everything that i cannot document, not having access to a LAN, for one thing. Also (c) Rumour has it that we are scheduled to get sunshine and warm weather from July 17th to August 3rd this year on this storm-swept tip of the peninsula

Please read the document NotesonIntroductionInstallationInitialSearchdoc carefully; I am driven by content, not formatting at this point.
That document and the section it documents can be downloaded in Word2003 format and in PDF format as VoidtoolsTutorial.zip

Cheers, Chris

[horst.epp]

That document and the section it documents can be downloaded in Word2003 format and in PDF format as www.chrisgreaves.com/Downloads/VoidtoolsTutorial.zip

Cheers, Chris

The link doesn't work.
The requested page could not be found

[NotNull]

And now?

[ChrisGreaves]

And now?

@Horst @NotNull

https://www.chrisgreaves.com/Downloads/ ... torial.zip

This pasted link just d/l a second copy for me. (I test my d/l links before "Submit"), so I believe that the link is working.

We have had intermittent failures throughout the day, but this seems to be internet access from Bonavista, rather than problems at my Hoster.
That is, throughout the day I have been unable to read news, youtube, forums, and have had to do nothing but work all day

Please one/both of you try pasting the link in this post and see if you can d/l the zip file now.

I apologize for the breakdown. What/wherever it is/was.
Cheers, Chris

[horst.epp]

It wasn't working, I know how to click links
Now it works

[NotNull]

That happens when there is no http(s):// before trhe url.

Example:

Code: Select all

[url=www.google.com]test[/url]

which leads to the following link:
test

Hover the link with your mouse and watch the statusbar of your browser to see what it expands too.


(BTW: I fixed the original link)

[ChrisGreaves]

That happens when there is no http(s):// before the url.

NotNull: Thank you, and thank you for the fix.
Whenever I upload a file for download I make a test by constructing the link manually in the URL box of Firefox (Ctrl+L) and then tapping <Enter> to execute the download.
The progress box pops up, I Alt+Tab to Explorer to see that the download has taken place, then Ctrl+C from the URL box and immediately Ctrl+V into the post.
So I am puzzled that in this case a non-functioning link was constructed.
On top of that I usually confirm links in a post by executing each one from the Preview pane before Submitting.
I shall pay more attention to my process in the future

Cheers, Chris

[NotNull]

I shall pay more attention to my process in the future

So far, all your links turned out fine; this was one went through the cracks. And it got caught anyway so no harm done
Paying even more attention would be a waste of time and energy.
And now I learned something new too as I was not aware of this mechanism. So: thank YOU!