search

SignalK / SensESP

Universal Signal K sensor framework for the ESP32 platform
https://signalk.org/SensESP/
Apache License 2.0
151 stars 81 forks source link

Make first Tutorial more concise #520

Closed ba58smith closed 2 years ago

ba58smith commented 2 years ago

Based on a conversation with @mairas.

ba58smith commented 2 years ago

You made several points that I agree with - certainly any of my text that's WRONG needs to be corrected, and the idea of explaining all of the boilerplate lines after explaining the "meat of the program" has merit. But the bigger issue is that you and I just have very different ideas about the point of a Tutorial / set of Tutorials; so different that I don't believe I can ever write them the way you want, because I don't agree with your approach. And that probably goes back to a deeper issue, of me not really understanding who your target audience is for SensESP.

I think, in order for us to remain friends (which I feel like we are), and to preserve our sanity with respect to this project, that I should back away from the documentation. When you publish it for Version 2, I'll read it, and decide then if I want to write a "Companion Guide for SensESP Newbies", and if I do, it will be a completely separate, independent project.

Sorry to have wasted so much of your time on this. Feel free to use anything I've written so far, and to edit the hell out of it.

mairas commented 2 years ago

I did write these comments assuming that the reader is an absolute newbie but does have some basic understanding of C/C++. I believe those were your assumptions.

Also, I've tried to explain that even though, yes, my own expectations for useful documentation are quite different, that doesn't mean there couldn't be material with totally different expectations and audiences. But if you specifically ask for a brutally honest review, I must assume you're interested in it, if only to understand our different points of view. I never assumed you'd act on all of my comments because of our totally different opinions on the matter. I don't really have a problem if you just go ahead and merge the PR as is.

mairas commented 2 years ago

Closing.