Manual updates

mjy58

Member
Being relatively new to PICAXE I have posted several questions for clarification about commands from Manual 2 V7.8. Today I wanted to clarify what to do with the address in a READ or WRITE with a word variable. There is no example of using the word variable in the manual.

The top 5 entries in this Google search
Code:
site:www.picaxeforum.co.uk write word
were asking exactly the same question! Some being answered better than others. From the results I now understand that the address needs to be incremented by 2 if using word variables.

My point is, that over several years the same question has been asked in this forum several times, but an example for using a word variable with READ and WRITE is still not in the manual.

I do not underestimate the problems of keeping manuals up to date. Would it be beneficial to have a thread specifically for proposed manual updates? The thread could be general, with the pros and cons discussed, but once 'approved' the first(?) entry in the thread is updated to show a summary of all changes that will be included in the next version of the manual.

This would allow newcomers to see issues that are being discussed AND aid the poor soul who has to update the manual, by having a concise list of agreed changes?

Perhaps,something similar to the 'Programming Editor Wishlist' with a summary at the front?
 

srnet

Senior Member
I needed to look this up myself earlier, I found the explanation in the manual clear enough;

When word variables are used (with the keyword WORD) the two bytes of the
word are saved/retrieved in a little endian manner (ie low byte at address, high
byte at address + 1)
 

mjy58

Member
I was merely using that as an example.

If several people have had to ask a question to clarify something, would it not make sense to include the answer in the manual as it may also be unclear to others?
 

geezer88

Senior Member
I needed to look this up myself earlier, I found the explanation in the manual clear enough;

When word variables are used (with the keyword WORD) the two bytes of the
word are saved/retrieved in a little endian manner (ie low byte at address, high
byte at address + 1)
These devices are being sold as student and beginner items. This is not obvious to a beginner.

still a beginner,
tom
 

mrburnette

Senior Member
A year ago, I felt the manuals needed a serious update, however I no longer feel this way. Rather, I think RevEd gets an A- for the manuals. I think many of the new members are overwhelmed with the PICAXE because-
1) Lack of point-of-reference for asking specific question(s)
2) Generally not well experienced with basic electronics (voltage drops, Ohm's Law, basic capacitor theory)
3) Attempting a project without research (students in classes are far more capable of asking quality questions)
4) Not investing in themselves (voltmeter, breadboard or project board, spare parts)
5) Difficulties or failure to utilize forum search

Now, #5 to me is where (perhaps) RevEd could assist, but the forum software may not allow 'search' to ever be a shinning star. I have recently been embarrassed by asking a question after doing several searches with an empty-results set. Yet, responses to my question were links back into the forum! Clearly, search is not perfect... nor am I :)

@mjy58 ... I have my own Word doc that I started and as I run into issues (command, function usage, etc.) I build my own examples and simulator code. When I start a project, I review this document. I then flowchart and pseudo-code sections. Using my notes, I write snippets of critical code so that it RUNS IN THE SIMULATOR and provides results consistent with my expectations. This is when, if things go askew, that the power of he forum is appropriate.

- Ray
 

HertzHog

Member
I agree there is incremental work to be done. Recently, I was grappling with what seemed a common problem. Monitoring the supply voltage of your project. I got hardware suggestions from the forum, but it can be done with a software only solution. The 'solution' was accepted and a code snippet put in a new example tab relating to the command with comments, in my case it was at example 2
http://www.picaxe.com/BASIC-Commands/Advanced-PICAXE-Configuration/calibadc10/
That seemed like an organic way for the manul to grow without burdening newcomers. HertzHog
 

srnet

Senior Member
The manuals are already substantial, and its going to make them much larger if examples of each option for each command are shown. And even for the included examples, there has been comment that they should be more substantial, working, bits of code.

What the manuals are not, and neither do I think they should be, is a from the ground description to begginners of all the terms and techniques for how to use Microcontrollers. Take the first few pages, the section on constants, variables and mathematics. There will be beginners, who struggle with these sections and fuller descriptions and more real world examples could be given. But should they ?

Perhaps there is scope for a 'basic' introductory manual\book, but I guess that comes down to time and money, who is going to volunteer ?
 

westaust55

Moderator
I suspect that a lot of it comes down to:
1. doing some searching (or knowing how to search). I have concurrent thread on the exact same topic!
2. knowing how to ask a good question (a topic covered once before)
3. providing sufficient supporting information from the start (the subject of proforma's for providing details and questions has been raised before)

Another thread has just been started also about the manuals, in particular Manual 2, suggesting a cross reference/Thesarus - not to say that it is not a worthy topic but always there are sugegstion on how to better do something.

Manual 3 could also be expanded to cover some additional interfacing - just have a look at the Parallax "Stamp Works" booklet.
The excercises therein also flag to readers to go and read up about listed commands.
However there are a lot of new electronic modules and sensors appearing out there in more recent years so where do Rev Ed stop in terms of trying to cover everything.

I find that often, the answer to many questions really is already in the manuals. In these cases while I give an answer, I frequently give a reference to the page No in the relevant PICAXE manual.

Those who have been on the forum for a few years (or more) invariably have some inkling what is therein. But how often are the "gems" of wisdom really looked at?
For example, recent there was a thread/post asking about Vcc, Vss, Vdd, Vee and what where the differences.
There is already a thread with a glossary of many common terms but in just looking at that thread and in particular the final attachment is has been viewed very few times.
See here: http://www.picaxeforum.co.uk/showthread.php?11867-Glossary-of-Terms&p=93709#post93709

A few decades ago there were no such things are forums or the internet. If the hobbyist, student or others wanted to learn how to use/do something then it was get the paper version of the datasheet and read then reread. Then followed experimentation (with trial and error if necessary).
The internet and forum have, IMHO, made it too easy to ask questions rather than search. There are folks on the forums who are willing to help nevertheless.
Some times the question is raised of the type: "will this work?". Often the question could be answered just by trying for themselves, but . . . . . maybe it is a lack of condfidence and it is easy to ask the question.

Over the decades, and often while living in very small communities and at other time very remote lcoations (eg 2,000 km from nearest electronics store - there was mail order), I have tried many experiments in electronics and read the datasheets to ensure I did not exceed rataings, etc. Some of those experiments did not work as expected and a few mot at all, however I could still count on one hand how many components have failed as a result of such experiments.

There is my 1 cent/pence worth -after tax :)
 

Dippy

Moderator
That's great value for just 1 cent Westy :) For a dollar you can write a nice Wiki.


Writing a Manual is tricky and time-consuming. It's a no-win for the authors.
It's impossible to please all of the people all of the time.
And the Manual is not intended to be a Beginner's Book.


But , quite often you can only understand something in a Manual when you already have some experience.
Srnet's reply in Post #2 is a prime example of that.
If I were a total eager newbie I wouldn't be able to tell my nibbles from my endian!


In practice a few extra examples, where space permits, would be sensible and nice.
After all, PICAXE is Entry Level so the target audience will tend to require a little extra assistance.
In the query posted by mjy58 , there is space on the BASIC Manual 2 page for an example using a word variable.
Even better - a small diagram to show how things are stored.
An hour's work for someone... not me.
In fact it would take Hippy less time to write 3 lines of code and do a drawing than it would take him to reply here - there's a thought huh? Come on Hippy, you know you want to ;)


Relying on a Forum to clarify the real basics is a double-edged doo-dah.
Yes, you can get some superb replies and help. Or you can get total boll.
In any event it's gone after a week
Searching Forums can be an absolute nightmare - the 'search' routine is simply not 'smart' enough.
You often have to rely on Old Hacks (or Eclectic) to remember and search for you.
An indexible Wiki listing has been mentioned many times but never appeared.


If you ever have to write Manuals you'll find it is a real chore.
And, in many other places, so much documentation assumes considerable experience, or just plain missing.
Anyone tried writing code for Android or Rasperry-Pi yet?
I have. Jeez, getting started was a real pain in the little endian!!


On the whole , the Rev-Ed Manuals are very good.
And to show I'm not being sycophantic I'll add that an explanatory tweak here and there would be good and VERY appreciated by many newbies and people thinking about buying.
I think I said the same thing 4 years ago ;)
 

HertzHog

Member
Well I think the forum should contribute to propose improvements to the existing examples by supplementing them with purposeful working code snippets with comments too. I think too many were written in haste and are of the
"Functionx On ' turns Functionx on"
type. Rather than the purpose for Functionx and it's syntax both being shown.
My example was interpreted, enhanced and standardised by Hippy too. That adds further value. There are plenty of potential tabs for these examples they are discretely hidden and could be inserted with some attempt at ordering by simplicity with the easyest being example 1 etc. HertzHog
 

mjy58

Member
I agree there is incremental work to be done. Recently, I was grappling with what seemed a common problem. Monitoring the supply voltage of your project. I got hardware suggestions from the forum, but it can be done with a software only solution. The 'solution' was accepted and a code snippet put in a new example tab relating to the command with comments, in my case it was at example 2
http://www.picaxe.com/BASIC-Commands/Advanced-PICAXE-Configuration/calibadc10/
That seemed like an organic way for the manul to grow without burdening newcomers. HertzHog
To prove how much I still have to learn:(

I did not know there was an online version of all the basic commands as shown by the link from HertzHog above. I think this provides exactly what I was suggesting in my first post:)

  • The commands are listed either alphabetically or by category (so easy to find and cross reference).
  • Comments can be left against each command AND further code examples can be added by forum members.
  • Reference can be made to this when updating a new manual release

So my only outstanding question is why did I not find about this earlier and how can it be made more visible to other new users?

[I will add an example of READ using the word variable, to this online version, when I have tested the code]
 

hippy

Technical Support
Staff member
I think too many were written in haste and are of the "Functionx On ' turns Functionx on" type. Rather than the purpose for Functionx and it's syntax both being shown.
One mustn't forget that a huge part of our audience ( and rarely seen on the forums ) wants precisely what we provide, just want to see a simple one line example of using the command, so not really haste but it is acknowledged that we do not always have the time and resources to immediately do all that we and others would like additional to that.

It's always difficult targeting any documentation to a range of abilities with the danger that examples are too simplistic for some and too complicated for others and one can end in a situation of it becoming less than suitable for anyone. There's also the reality that the people who are capable of what an advanced example covers do not actually need that example to help them so there's always a potential risk of a lot of effort for little real gain.

That's not to say there is no need for more explanation and examples, introductory, intermediate or advanced content, but just that it's not always such a simple problem to address as it may seem. The major thing we have added is the ability for people to submit their own examples for the online documentation and we would be delighted if people took the opportunity to do that -

http://www.picaxe.com/BASIC-Commands
 

Dippy

Moderator
Excellent!
That's the first time I've seen it mentioned. A really nice feature. Very useful.

Just one Question; do you go through it now and then to check for accuracy of submitted examples?
I'm sure other contributors can check but I was just wondering if it was verified - just in case an erroneous example sits there for weeks...

Please can you advertise it in big letters on the Forum... it could save people loads of time.
 

mjy58

Member
Online help link

From Program Editor;

Help\Online Support\Picaxe Manuals\Commands
Interesting, that link only works if you have a program loaded in Program Editor. Without a program loaded it takes you to the Rev-Ed home page:confused:

Perhaps, now we have this (interactive) online facility, there should be a link to it in each of the manuals as well as from the 'Help' in Program Editor?
 

westaust55

Moderator
So my only outstanding question is why did I not find about this earlier and how can it be made more visible to other new users?
It is worth all forum members taking the time to visit the Rev Ed website and undertake a look through the various sections to understand what is there.
There is a lot there that it would seem many are not aware exists. Even just knowing what is there by looking can be helpful to find information when the need later arises.
 

mjy58

Member
It is worth all forum members taking the time to visit the Rev Ed website and undertake a look through the various sections to understand what is there.
There is a lot there that it would seem many are not aware exists. Even just knowing what is there by looking can be helpful to find information when the need later arises.
Agreed, although it does sound from the replies above that the 'Online Commands' section is relatively new.

Perhaps there should also be an 'Announcements' section on the website that details any major changes or new additions?
 

westaust55

Moderator
Agreed, although it does sound from the replies above that the 'Online Commands' section is relatively new.

Perhaps there should also be an 'Announcements' section on the website that details any major changes or new additions?
Well yes, the entire Revolution Education (Rev Ed) PICAXE website was upgraded to what you now see some months ago.
As per the link by Martin57 it was announced just over 6 months ago on 8 September 2011.
http://www.picaxeforum.co.uk/showthread.php?19303-New-PICAXE-Website

The forum has 58,000+ members but that link has only had around 1700 views. Therein lies the problem - many do not read the available information.
6 months is not particularly new in these times when new electronics items are coming out from worldwide suppliers every day.
 

hippy

Technical Support
Staff member
So my only outstanding question is why did I not find about this earlier and how can it be made more visible to other new users?
It's perhaps mainly that there's not currently the level of integration between Programming Editor and the web site that is likely to be present with future versions, and most long term users are more used to having and using the information in manuals than online so naturally point people to those.

I've made a note about considering additional attempts and methods to promote the presence of the online data.


[I will add an example of READ using the word variable, to this online version, when I have tested the code]
No need to worry; I have added a READ and WRITE example for word variables.
 

Dippy

Moderator
"I've made a note about considering additional attempts and methods to promote the presence of the online data."

- thanks hippy.
PS. Love the jargon :)
 

mjy58

Member
No need to worry; I have added a READ and WRITE example for word variables.
Thanks hippy, an excellent example and explanation:)

Dippy said:
Judging by the fact that I haven't seen this mentioned before it would be nice to give it a permanent Forum link too.
Having only just started using this online commands section, I think it is such a useful supplement to the manuals, a permanent Forum link would be extremely valuable.
 

hippy

Technical Support
Staff member
No need to worry; I have added a READ and WRITE example for word variables.
Thanks hippy, an excellent example and explanation:)
It was relatively easy in one respect; that it was clear what needed to be illustrated so, half the work done, just a question of doing it and finding the time to code it, test it, and document it.

When it comes to esoteric or complicated examples ( and the same applies to datasheets and tutorials ) it's often not so clear cut, may be a massive subject in itself and I ( and other staff ) may not have particular experience or expertise in those areas.

Classic examples where things seem simple, and therefore seemingly easy to provide for but are not, are decoupling capacitors and driving MOSFET's. For decoupling my approach is to simply add 100nF capacitors where I think they will help and I have very limited experience of MOSFET's so I'm not best placed to give definitive, full or even correct advice on either. Copyright means I can't simply re-use someone else's work and, even if I could, I don't have the level of knowledges to assess all they've written or know what they haven't included that may be important.

RF, serial and networking they are massive fields in themselves and it's not easy to cater for all possibilities nor provide all 'how do I use it to achieve what I want' answers.

Some seemingly simple subjects such as leaving inputs floating or inputting voltages higher than the PICAXE power supply don't have a definitive or simple answer and no matter what is written it will often be disputed and argued over so requires very careful consideration of how things are worded and even then won't always answer the "so, what should I do" questions.

It's easy to say 'you should provide this' but it's not always so easy to actually provide what is asked for. That's why we are always pleased to have people who do have the experience and skills in a particular field provide their knowledge for others
 
Top