How to attract more documentation contributions? [was: CC3000 Socket error -1 while sending]

[espruino-discuss2]

Posted at 2015-03-03 by alexanderbrevig

Hi! I'm having an issue that I don't know how to fix.

I'm using code similar to this:

var wlan = require("CC3000").connect();
wlan.connect("SSID","PASSWORD",function(s){
  if (s=="dhcp") {
    var payload = {
      NodeId:1,
      Channel:"temperature",
      Value:23.5,
      Metric:"celcius"
    };
    var strPayload = JSON.stringify(payload);
    var options = {
      host: 'requestb.in',
      port: '80',
      path:'/wt3kigwt',
      method:'POST'
    };
    var req = require("http").request(options,function(res) {
        console.log('STATUS: ' + res.statusCode);
        console.log('HEADERS: ' + JSON.stringify(res.headers));
        res.on('data', function(data) {
          console.log("   " + data);
        });
        res.on('close', function() {
          console.log("closed");
        });
    });
    req.on('error', function(e) {
      console.log('problem with request: ' + e.message);
    });
    req.write(strPayload);
    req.end();
  }
});

Check results here http://requestb.in/wt3kigwt?inspect

For this I get Content-Length: 0 which is a problem because my API needs this header to function properly (can't do anything about that) so then; let's try to add the header:

var options = {
      host: 'requestb.in',
      port: '80',
      path:'/wt3kigwt',
      method:'POST',
      headers: { "Content-Length": strPayload.length }
    };

Now, one of two things happens:

1. Socket error -1 while sending
2. The espruino simply hangs, last output is >echo();

I have tested this with both 1v73 and 1v74, I have yet to make a successful POST to my API.

Any ideas?

[espruino-discuss2]

Posted at 2015-03-03 by alexanderbrevig

While I wrote my post I disconnected my Espruino. Now, after plugging it in and uploading the changed code (with headers:) it works!

However, if I reset the board and try again - the problem seems to occur again.

Spending a few seconds (10-15 seems to do the trick) between each test is somewhat of a productivity sink, but I can live with that...

Sorry for posting before trying the 'obvious'

Did you turn it off and on again?

[gfwilliams]

Posted at 2015-03-03 by @gfwilliams

That's a strange one - I guess it could have been some kind of CC3000 issue. I'll keep an eye on it though - it could be some problem with resetting the state of the HTTP client.

I'm surprised about the Content-Length field - are you sure the website you tried with hasn't just made that up? I thought usually it was just omitted.

It's a bit late now, but there is an example of sending to Xively (which does very similar stuff) here: http://www.espruino.com/wifi_humidity

Glad you got it working in the end though!

[espruino-discuss2]

Posted at 2015-03-03 by alexanderbrevig

I looked at that Xively sample (that's how I discovered the headers field, it's not documented in the reference - maybe it should be added?).

It's an OData backend, my guess is that they enforce it somehow, either OData standard, or the .NET implementation of it.

I have a working workflow now, so all is good :)

EDIT: Because I realized I could add the simple ",headers" to the doc string myself I did and made a PR for it here.

[gfwilliams]

Posted at 2015-03-04 by @gfwilliams

Thanks for the PR - that sort of thing is amazingly useful.

A bit off topic - but any thoughts as to how I could encourage more contributions like that? I could add an 'edit' link to the reference that takes you to the exact line number on GitHub?

[espruino-discuss2]

Posted at 2015-03-04 by alexanderbrevig

That'a a very good question, and a good proposal. How would that work for people that already has a fork? Not used to the GitHub editor, but could anyone propose changes directly on the files in f.ex /Espruino or would they need to then locate the same file/line in the forked repo under their account?

---

Apologies for the long blurb to come:
In a very 'typical me' fashion, my brain started spinning and here's my initial thought:

Another way to encourage these kinds of contributions (and this would've applied to the situation I was in yesterday) would be to have some kind of listing of places where documentation is considered lacking or out of date. Something like wikipedia has.
When I made this very small PR I was actually looking for more things to do, but gave up.

What if sections in the doc had some links like "edit", "lacking" or "out of date" and then these could append to a list somewhere (except edit, which would either point to file@line or open an editor on github if that is feasable). These links could of course toggle their visibility on hover, or by clicking a "contribute" button in some standard location on each page.

I don't know if your site is purely static or if you have some kind of language serving them, but if you do have a server side language - I could help write the simple tool for this. It should be relatively simple to make an endpoint:

1. POST /report/needwork?description=headers not documented&file=/path/to/filename.c&line=12
2. DELETE /report/needwork?file=/path/to/filename.c&line=12

If a section in docs needs work, then user clicks "out of date" and a POST is sent. Then, when it is fixed - either the fixer or the next user that comes along can certify the fix by clicking again, causing a DELETE.
This would then be completed by a route which generates a view of these entries.

description            | github link 
headers not documented | jswrap_http.c@236

You would then need to have a script running on the doc pages that determines if any given section is in need of work or not, changing the "out of date" link to something like "up to date".

EDIT: mockup of edit/report per section feature attached as image

---

Attachments:

• espruino_contribute_docs.png

[gfwilliams]

Posted at 2015-03-04 by @gfwilliams

I think you have to make changes in the GitHub fork, so it's not going to be super-easy for someone that hasn't used it before.

The website is mostly static but is served up using php, so I could definitely add something active to it if needed. Perhaps the easiest method is actually just to come up with a webpage with a markdown editor built into it. For now I could even check and apply the changes manually.

The 'needs work' is a good idea, but to be honest by the time someone's written down what is wrong they might as well have written the correct documentation. I could just include a note that prefixing a line with 'FIXME:' signals you want something clarified.

[espruino-discuss2]

Posted at 2015-03-04 by alexanderbrevig

You're thinking along the lines that you will give the user a 'copy' of the relevant file in a markdown editor. Then when user saves, you get that file on your server somewhere - then diff it into the github?

Definitely a simpler solution than the table thingy I thought of. You could actually just use the same copy of the file until you merge as well (probably what you thought about doing).
A good idea about the FIXME: too, this way it's the same interface for contributing with the fix as it is with contributing with the 'needs work'. I like it.

[gfwilliams]

Posted at 2015-03-04 by @gfwilliams

Yes, that's the plan...

Now I just need some time to do it :)

[espruino-discuss2]

Posted at 2015-03-04 by @allObjects

my brain started spinning and here's...

I like that...

While using the reference, I missed the back linking of the heading to the next higher heading and at the top to table of content... since the page html is php generated, something like that could play into a bigger picture: if there is not a flexible caching in place for a composed page, the page html should not be built every time it is called... page build should only happen when content has changed. I know that is easier said than implemented when the page has independent components. It is though not difficult when the page is 'decorated only'. Decoration only does not need other components and therefore also not the information if they have changed or not.

[gfwilliams]

Posted at 2015-03-05 by @gfwilliams

since the page html is php generated

It's actually not - pretty much every page is static, but is just served up with PHP that sticks a header and footer on it... It's all relatively speedy.

The reference page is created with this Python script. Ideally I'd swap it all over to JS though as the python is getting nasty very quickly :)

Still, if you want to add extra things (links to the top/etc) then PRs are welcome :) It might even be easier (and would save a lot of bytes) to add a <script> tag to the top which would scan over headings and then add links to the top on the client.