Stack Overflow Documentation and Meteor


#1

Today Stack Overflow announced the Stack Overflow documentation beta. It’s great to see Meteor logo between the first beta participants.

I find the core idea great and a fan of example based documentation.

What are your thoughts about this? As a community – should we be more active on [the official Meteor guide’s] (https://guide.meteor.com) github, focus on this forum or help to create an alternative?


#2

Here’s the way I think about it:

  1. The Meteor Guide is an opinionated resource - it focuses on just having one reasonable way to solve each problem
  2. The forums are for individual help - you can ask questions and get answers (you can also use Stack Overflow, but sometimes people think the community here is nicer)
  3. SO Documentation is for community examples, guides, and code snippets. There should be tons of different way to do everything, and people can vote to figure out the best ways

So (3) could be a good way to publish some speciifc insights you’ve gained - if you figured out a cool new way to do something, that would be a good place to post it! I think linking to those things from the forums is cool as well, until people get used to that website.

We’ll see how it goes!


#3

Alright, let’s get the ball rolling then!

Could someone please review this http://stackoverflow.com/documentation/meteor/drafts/17137

And let’s hope the community likes this and picks it up!

I remember everyone being very keen on an enhancement on the official docs where we could contribute examples, here’s that chance!

Edit: Ping @tmeasday @zoltan I think you guys are the only two people currently able to review my draft :slight_smile:


#4

Hopefully we can figure out a way to link relevant docs to the right parts of Stack Overflow if it takes off!


#5

Alright! We got our first bit of content :]


#6

We still need to figure out how to coordinate this thing, though.

It seems @corvid and I created very similar topics at almost exactly the same time and I cannot figure out how to start a workflow that merges those two!

Edit: got it! sumitted the reorganization for approval if anyone’s interested!


#7

Also, for those unaware, you should join the Meteor gitter: https://gitter.im/meteor/meteor

It’s probably the best place to get real-time chat help for Meteor.

I do Android development as well and the official Android IRC is an invaluable resource, so the more active people we can get in Meteors gitter channel the better.


#8

I’m a big fan of the Meteor Chef slack as well: http://slack.themeteorchef.com/

But I don’t think Slack is a good way to produce lasting educational content for people.


#9

I noticed that, let’s contribute to yours and delete mine. I added a few little helpful examples to yours.


#10

Hey! Did that finally get released? Nice. Looking forward to finally having a place to migrate a bunch of Meteor Cookbook recipes, and repurposing that repository as an SDK.

Can we get tags for Blaze, React, Angular, Vue, etc?

Hmmm… okay, so most of the Cookbook examples could go in as Meteor 1.0 or 1.1.3 examples, I suppose. That makes some sense.

Ooooooh… I’m liking this.


#11

I think we’re about to see the existing 10+ examples to expand to a 1000+ :slight_smile:


#12

Yeah, have about three years worth of recipes that can go in here. Don’t know about 1000 recipes, but there are at least 100 articles in the Cookbook, with an average of 3 to 5 recipes per article, maybe? So I’d guess around 300 to 500 examples? Maybe a third to half are Blaze-centric? And the rest are UI agnostic.

If anybody wants source material and examples to write documentation with, the Cookbook is now sitting in the Clinical Meteor SDK repository:

And the Table of Contents:

https://github.com/clinical-meteor/software-development-kit/blob/master/table-of-contents.md


#13

I tried to include some fairly more “advanced” use cases I’ve run into in my day, I think those might be super useful.


#14

Super excited about this you guys!


#15

Some guidance would be helpful …

I started writing something and then realised I was just regurgitating (albeit in a highly condensed form) information already in the Guide. My feeling is that’s not what this is about. That this should be for specific (real world) use case examples.

Is that correct?


#16

Has anybody gotten syntax highlighting working in the examples yet?


#17

How do we deal with people who only know how to criticize and complain, and can’t add constructive comments?


#18

What are you referring to?


#19

@sashko I think what @awatson1978 is referring to is - since there is only one topic awaiting review - this one

I am sad that I am participating in this conversation but I honestly cannot get over this, especially since it is coming from you @awatson1978 whom I have nothing but high respect for. You were one of the people who inspired me to have a change of career, build trust and respect for a technical community and do my best to pass that torch on to others.

I wish we had this conversation in private, but as I said, since it is out in the open, and that said topic is indeed the only one sitting there, I cannot let this go like this.

Let me first, apologize to you, sincerely, if my comments made you feel the way you did. They certainly were not meant to be as such, in fact I was thinking - still am - that I was as constructive and respectful as anyone - critiqueing peer work - can get.

I thought I did offer my thoughts on in which way I beleived those pieces of documentation were less than perfect and how they could have been improved. But I do admit that I would have done a better job conveying that message had it not been for the nature of stack overflow with comments being tight in space, encouraging comments to be as succint as possible.

I also thought, by not rejecting them, I made it even clearer that I did agree with the overall content and just hoped for it to be clearer in parts I thought I explained were not.

And I could not bring myself to approve them - regardless of the respect I have for you and my appreciation for the overall message - either, since that would have been somewhat against my own principles, approving something that I don’t quite agree with, that is.

Anyway, they are there for anyone interested to approve as is.

I’d also like to apologize to everyone for setting the course of this topic somewhat off. But I hope it can serve as a means to a discussion on how we can - as a truly great and inspiring community - use stack overflow documentation in better ways and perhaps even foster our own code of documentation conduct.

Finally, thank you again @awatson1978 for taking the time to even attempt to copy over years of work, it is a huge undertaking and I hope you don’t get discouraged by this disagreement we had.

:heart:
Serkan


#20

Dude, it’s not about the critique. They’re fine. (Even if I disagree with them.)

I’m irked about the process. There’s not easy editing of an initially submitted document. One has to retract the entire document and resubmit it. And each one of these is taking me 10 or 15 minutes to put together, even if I’m copy-pasting them. Edits, typos, formatting… it takes time.

I don’t mind you making comments and critiques. I would just really, really appreciate to have them after the document is in the system. As part of the improvement process; not part of the initial review process.

I have like 100 of these to get through. Let me just load up the content, so people can get start improving it. If it goes into the system, and people decide to delete it, rearrange it, rewrite it, I promise I won’t care. I’ve got graduate school and three client projects to be working on. So my plate is full. If each one is going to be a hassle to get approved to even be accepted, I’m just going to walk away and work on other projects (that I’m getting paid on).

As for that full installation, it’s probably gone through 80 or 100 reviews and installs. So, I’m sort of done with it. Either take it or not. If you see improvements that can be made; great. Let’s do the improvements. But there’s a reason this type of document wound up in the Cookbook… because people asked for it. Repeatedly. And I’m trying to donate it to the cause.

We’re just figuring out the process, so it’s cool. People get hot and on each other’s nerves. So apology accepted if that will assure you.

I’m just looking at this from a different angle; trying to migrate an entire cookbook. Please understand that the submission tools are a little less flexible than one might prefer. It’s still in beta afterall. No harm done.

Just… try to work with me, rather than putting up roadblocks as I load the content in. Then, go to town. :slight_smile: