Documentation

[Naptalene]

Hi everyone,

I sent a PM to Roberto about documentation for the RA.
He supplied me with these links:


https://github.com/reefangel/Libraries/wiki

cosmith71 started a beginners tutorial here:
viewtopic.php?f=14&t=3353

lnevo generated a doxigen dump of the libraries and posted in his server:
http://www.easte.net/ra/html/

This final link is what quite a few more advanced people will be looking for (i had never come accross it) but it's still out of the league of people such as myself.

Sooooooo, what I would like to propose is the following...

We try and create a user manual for the RA, but for normal people
I was thinking that the following format would work well:

We start with the bits of a standard RA, for each unit or port, we show it and tell the User what it's called in the code, why it's called that and how it's implemented.

For instance,
Show I/O ports, and explain that its a switch that only has an on and an off status.
therefore we use "If" this, then do this, "Else" do this.
A common use is for ATO so it has a default name of "ATOhigh"
etc....

Then we could get all the Doxigen info and create a referance list of that at the end for advanced guys.
It's a big undertaking as the unit is so flexible but I do believe that we could get a document together that would make new users with no coding background feel far more comfortable with the RA and not be intimidated.

What do you guys think?

[cosmith71]

I've been thinking about this for a long time. The problem is, there is sooooo much and it changes very, very often. It seems overwhelming.

I think something basic would be a good place to start.

--Colin

[Naptalene]

Agreed

But what if we aim it at the most basic user and work from there.
Lets face it, the really advanced stuff that changes radically is the stuff where you guys are custom coding for specific purposes. I don't get the feeling that's where the fundamental problem is. IMHO it's guys in the following situation that are having problems.

Fred Bloggs gets his ReefAngel and wants 3 Temp probes.
He plugs them in. Is T1 always the first connector on the head unit? Is T1 assigned by a unique identifier?
He uses the Wizard and has T1 as his main probe but now wants to get T2 to trigger something else and T3 yet another thing (fans on heatsink maybe)
We should give a simple referance code like this:

if T2>265 ReefAngel.Relay.On(Port2); // This means if T2 is greater than 26.5C turn on Relay port2

Aside from the fact that I probably just got the code wrong, that would seriously help a new user to have.
To try and figure out that simple thing when you dont have a clue is quite difficult. And when you look at the existing codes, you see the library calls for T1 which make no sense if you're trying to do the simple thing as above.

Does it make sense to do it that way?

[Naptalene]

And I must apologise, my brain scrambles all over the place, so if things are vague or I seem quite "in your face" its not the case

[Naptalene]

Here's a prime example of something that should be available for new users....taken from RMCs Humble Code Abode

{
ReefAngel.StandardFan( Port1,800,810 );
ReefAngel.Relay.DelayedOn( Port2,10 );
ReefAngel.DosingPumpRepeat( Port3,0,20,60 );
ReefAngel.DosingPumpRepeat( Port7,0,20,30 );
ReefAngel.StandardLights( Port8,11,0,19,0 );
ReefAngel.PWM.SetDaylight( PWMParabola(8,0,20,30,15,100,15) );
ReefAngel.PWM.SetActinic( PWMParabola(10,30,20,30,15,100,15) );
////// Place your custom code below here

Each of those lines should be in a document with an explanation for what they are......
So in the manual we could have a chapter "Dosing Pumps"

these are the calls for that class (put them down) and for this, the numbers in the brackets mean:
Relay port of the Pump.... and then I actually dont know what the rest are lol. We can clarify that sort of thing easily.

[lnevo]

I've always said that if someone organizes the wiki with the headings of what examples are needed i and anyone who wanted can contribute relevant coding blurbs.

If you would volunteer to create the outline and keep a thread here of what needs to be filled in it would get done fairly quickly

[cosmith71]

So I'm messing with the GitHub Wiki, trying to copy over the "How the Code Structure Works" post.

What's the best way to author stuff for this? It's definitely not WYSIWIG. It's not even friendly like the forum editor.

--Colin

[rimai]

It is WYSIWYG.
I think you just need to get the correct privileges. I thought anyone could do it, but I guess I'm wrong.
Were you logged in to your github account?
I just sent an invitation to join our dev team anyway.
There should be an edit button on top of the page.
You can also fork the repo, work offline and send a pull request. Just like the work you did on the libraries

[cosmith71]

Yeah, I get an editor that starts out in "Markdown" mode (with several other modes available). I switched over to Org mode since it seems to be a little easier to convert the forum codes to. Am I missing something else?

--Colin

[rimai]

That's it

[cosmith71]

That's what I was afraid of.

I found a stand-alone Markdown editor that looks promising.

I can't seem to clone the Wiki section. I hit "Clone in Desktop" and the desktop app gives me a big error.

--Colin

[Naptalene]

Ok, I have no clue how to do any of the Wiki stuff but I can happily try get headings etc. together as a structure and keep this thread running.

But you guys do realize the standard, off the street user has no clue about github at all?
They are used to a file they can just click and get the info.
Maybe some "normal" users can chime in here?

[jegillis]

Im a "normal" user and I know what github is my grandmother not so much. Any user can click a link to the Wiki the fact that it is on github should not make any difference.

[Naptalene]

Ok cool

[lnevo]

The only thing that we need and the reason for a wiki is it's a central way for us to maintain a document. We could just as easily create a google doc that we can update too. Doesn't matter to me. Just once we're done whether its this thread or another, tell me what examples you want and we can start coding. I'd rather answer one person's question once and have someone put it into the central doc then answer the same question 10 times on the forum anyday

[Naptalene]

Question....

Are we going for a manual on the RA bits and their unique code, or an area of "Cutnpaste" code of commonly requested code that you can tweak? Or possibly both? Sorry to be pedantic but I think that if we have a clear idea of what we're going for it will be easier to attain.

[cosmith71]

Definitely both.

[lnevo]

I can either supply code blocks or explanations of how things work. Doesn't really matter to me. What do you think "normal" users would need... I'm fine with both

[Naptalene]

Hi, my name's Andrew and I'm Normal lol.

I think it's settled for both ideally.
What if we do this for structure:

RAplus

1. Std Relay unit

1.1 description
1.2 port names
1.3 defining user assigned port names
1.4 how to turn ports on or off
1.5 example using T1 as main probe with in depth comments
1.6 links to Temp probes

2. Input ports

1.1 description
1.2 port names
1.3 defining user assigned port names
1.4 how to read the status of the input
1.5 example using standard ATO code
1.6 commonly requested code
1.6 links to relay,

On temp probes we could link to PWM as well and show how you can change fan speed based on probe reading.

What do you think?

[jegillis]

Could go through the How do I section and make an article for the most commonly requested items.

[lnevo]

I'm not sure what is expected for some of those headings.. but that's cause I'm not a normal user.

What are "links to Temp probes"

How do temp probes get classified under the relay unit?

I don't think there's any user-assigned port names for input ports..

[Naptalene]

A Link to the section on temp probes.... Not sure what else I can say?
You would've just had T1 in the example so link to that item so guys can learn.

I forgot that I re-labelled my input and output ports via the portal and not in the code.
My ATO high is "skimmer kill" and low is "power status" or vice versa, I can't recall.
So we get rid of that. I'm just trying to get a layout that you guys think could work.

[Naptalene]

I just re-read your post.....

I think you see it as a "class and commands for that class" document and in my head I think of it as an almost linear read like an instruction manual.....

I'm really feeling like the village idiot talking to the wisemen right now.

[rimai]

Hi, my name's Andrew and I'm Normal lol.

I think it's settled for both ideally.
What if we do this for structure:

RAplus

1. Std Relay unit

1.1 description
1.2 port names
1.3 defining user assigned port names
1.4 how to turn ports on or off
1.5 example using T1 as main probe with in depth comments
1.6 links to Temp probes

2. Input ports

1.1 description
1.2 port names
1.3 defining user assigned port names
1.4 how to read the status of the input
1.5 example using standard ATO code
1.6 commonly requested code
1.6 links to relay,

On temp probes we could link to PWM as well and show how you can change fan speed based on probe reading.

What do you think?

I like the structure

[Naptalene]

Coolest.

I'll try make a list like that for all the units/ expanders to start off with.

And as mentioned using the "how do I code" thread as a reference for commonly needed code is a great idea.
Do you guys have a clever way of figuring that out or shall I be DataCapturer 1st Class?

[cosmith71]

I just re-read your post.....

I think you see it as a "class and commands for that class" document and in my head I think of it as an almost linear read like an instruction manual.....

I'm really feeling like the village idiot talking to the wisemen right now.

I understand what you mean. You want something that introduces a topic and then explains how it works, right?

--Colin

[Naptalene]

Yes!!! Thank you for putting it into English. I don't think it's just me who would appreciate it.
And perhaps we then have a final point for each topic which would link to a proper Referance list for the more serious coders, so it's all there for them/you guys.

[lnevo]

Yeah sorry just trying to understand the laymen's perspective. I frequently don't think about naming ports for the portal or screen than i do for usage in the code....just trying to follow the other view.

[lnevo]

I think screen labels are generic we should have a section for naming things and break out the different kinds of naming

[cosmith71]

One way to do it would be to break it down into systems.

Relays, programming relays, naming relays, dosing pumps, etc...

DC Pumps, modes and programming.

PWM lighting

etc