Page 1 of 1

ADRIFT Manual

PostPosted: Sat Mar 02, 2013 7:24 pm
by Campbell
Due to overwhelming demand, I have started work on a "proper" manual for ADRIFT 5. There will be two versions - a context sensitive (i.e. it will be possible to go straight to the relevant section of the help directly from the application) offline version, and an online version.

You can see the online version in it's current state at http://help.adrift.co. Please remember that it is still under construction. However, I would welcome any feedback.

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 5:35 am
by saabie
I love the nice clear look of it, and the treeview index makes it very fast to navigate to the page you want.
Using the terms general function and expression function is good as I have never known what I should be calling the different types of function in ADRIFT.
But this has made me wonder about the term "object oriented function".
It is very long-winded, necessitating the abbreviation "OO" to try to shorten it.
It is also very much a programmers technical term that might sound daunting to non-technical people.
Perhaps a more ADRIFT-relevant name like "item function" or "property function" would be simpler.

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 8:24 am
by Lazzah
saabie wrote:It is also very much a programmers technical term that might sound daunting to non-technical people.

I very much like the new manual but I do think it would be a good idea to provide a "Glossary of Terms" to explain what some of the technical terms mean. The first time someone mentioned a "disambiguation prompt" to me I had no idea what they were talking about.

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 9:42 am
by Campbell
I added a glossary section - I just haven't added that definition yet.

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 9:46 am
by Campbell
saabie wrote:this has made me wonder about the term "object oriented function".
It is very long-winded, necessitating the abbreviation "OO" to try to shorten it.
It is also very much a programmers technical term that might sound daunting to non-technical people.
Perhaps a more ADRIFT-relevant name like "item function" or "property function" would be simpler.
Yes, I agree, I will rename them.

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 3:51 pm
by P/o Prune
It looks great Campbell. I don't know what else to say :wink:
This is what I've been longing for... that and a huge increase in my salary ... but one of two isn't that bad either. :yeah:

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 7:16 pm
by NickyDude
saabie wrote:I love the nice clear look of it, and the treeview index makes it very fast to navigate to the page you want.
Using the terms general function and expression function is good as I have never known what I should be calling the different types of function in ADRIFT.
But this has made me wonder about the term "object oriented function".
It is very long-winded, necessitating the abbreviation "OO" to try to shorten it.
It is also very much a programmers technical term that might sound daunting to non-technical people.
Perhaps a more ADRIFT-relevant name like "item function" or "property function" would be simpler.


I too notice it leant towards the more technical side of writing with things like 'child', 'parent', 'node' and "To use the value of a property in an expression or a text box, use a location function." I'm guessing manual writing isn't your strong point Campbell... 8)

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 8:15 pm
by reelyor
VERY nice!!

Re: ADRIFT Manual

PostPosted: Sun Mar 03, 2013 10:32 pm
by Campbell
NickyDude wrote:I'm guessing manual writing isn't your strong point Campbell... 8)
Thanks for that. You do know I'm busting a gut here...

The manual is based off the Wiki which has been round for some time. The reason I went for a wiki in the first place was so it could be a joint effort. If you don't like the way something is written or explained, please, re-write it to something more suitable!

Aaarggh

Re: ADRIFT Manual

PostPosted: Mon Mar 04, 2013 6:55 am
by Lazzah
Campbell wrote:I added a glossary section - I just haven't added that definition yet.

Maybe you could move the glossary to the beginning of the manual where it is more noticeable? At the moment it is buried way down near the bottom of the tree. The reader might need to know what these terms are before they start looking for whatever section of the manual the wish to read. I would also give an example of a disambiguation prompt just to make sure they are fully aware of what you mean in you explanation of the term.

Re: ADRIFT Manual

PostPosted: Mon Mar 04, 2013 8:07 am
by Campbell
If you look on Wikipedia, "Traditionally, a glossary appears at the end of a book and includes terms within that book that are either newly introduced, uncommon, or specialized.". I think this is the most sensible place for it. It's not difficult to find, and I daresay not everyone will need it.

Re: ADRIFT Manual

PostPosted: Mon Mar 04, 2013 9:15 am
by Lazzah
Campbell wrote:If you look on Wikipedia, "Traditionally, a glossary appears at the end of a book and includes terms within that book that are either newly introduced, uncommon, or specialized.". I think this is the most sensible place for it. It's not difficult to find, and I daresay not everyone will need it.

Point taken. :)

Re: ADRIFT Manual

PostPosted: Wed Mar 13, 2013 8:55 pm
by NickyDude
just want to say you're doing an awesome job on the manual! Image

Re: ADRIFT Manual

PostPosted: Wed Mar 13, 2013 10:04 pm
by Campbell
Thanks, that means a lot! :-)