Documentation, again

General
41

Hi all (and especially @psb777),

Apologies for my delayed response here. Let me provide a bit of an official response from Spark.

Our docs need a lot of work. They represent the way that most people will learn to use Spark, and we need lots more content! Also, we’ve made a lot of changes to our firmware recently and the docs have fallen out of sync, which causes inaccuracies.

Internally at Spark, we’ve started trying to do Documentation-Driven Development where we document before we create a feature and then implement the feature to match the docs. We’re still learning how to do this; documentation is currently an afterthought after delivering a feature, where it really is the most important part since it defines how people understand and use the feature. This is something we’re trying to get better at.

@psb777 Your point that it should be easier to contribute to our documentation is very well taken. However, I don’t think a wiki is the answer. The reason is that, while wikis with lots and lots of contributors turn out pretty great (i.e. Wikipedia), wikis with a small number of contributors can become messy and unwieldy, and in particular unorganized. Look at the wikis at Seeed Studio as an example; I think if we had a wiki that’s more like what it would become.

I think it’s important that our documentation be reviewed the same way that our source code is; after all, it is as important as the source code. That’s why we use Github and pull requests. This may remove the satisfaction of making an update and seeing the website change immediately, but be patient!

All that said, I’d like to make some immediate changes to the documentation to resolve some of these issues. They are:

  • As of today, Spark Elite can accept pull requests to the docs. That will hopefully improve responsiveness on docs changes, since the Elite often get to this stuff before the team does :slight_smile:
  • I am working on a refactor of the documentation that will include changes to make it easier for a Github n00b to make contributions. Basically, each page will have an “edit” button that will link them to the Github edit page for the Markdown content, i.e. here: https://github.com/spark/docs/edit/master/docs/start.md
  • This refactor will also include some significant changes on the organization of the docs (better navigation so we can continue growing the content and still make it possible to find stuff), and the docs will be statically generated rather than generated through Javascript, which will make it easier to load up the docs locally on your machine, and also will improve linking to content.

I hope to finish this refactor this week, but as CEO, sometimes other stuff gets in the way; if you’d like to see what I’m working on, check out my feature branch: https://github.com/spark/docs/tree/feature/server-side-rendering

The other thing that I hope to do that will take a bit longer is make some gitbook tutorials. Check out this amazing project for creating great tutorials: https://www.gitbook.io/

Thanks @psb777 for raising the issue, hopefully this is a decent answer to your concerns.

Z

8 Likes
42

@Zach,

I just popped a pain pill as trying to use Github as a contributator for documentation is very, well, painful.

To be fair, then pain pill is for the teeth that jumped out of my mouth from grinding away at trying to figure out why you folks are taking away valuble memory from the spark core for online functions like Spark.publish

Okay, to be absolutely fair and clear - I and people like PBS77 are not going to contribute to docs as long as they are on Github; sorry but, its not just me.

43

How about contributing to the docs and letting someone else get your contribution into GitHub for you? That's what I'm wanting to do. You guys have tons of valuable knowledge that definitely should be in the documentation, so I want to help facilitate that!

2 Likes
44

Well, as long as "people like you" keep refusing to write documentation simply because it's not on their beloved wiki, we're going to have a hard time filling up the gaps.
I personally don't care whether or not you want to upload it to Github, it simply needs to be written. I don't know whether you guys just ABSOLUTELY love the wiki text editor, that makes you want to write on a wiki exclusively, or that you just really hate Github, and are protesting. For all I care you write it using notepad, or Word, or any other program/website, as long as it's written.
You guys seem to have valuable knowledge, and it would be a shame to let that go to waste over a deep rooted hate against Github.
If you would write documentation to the best of your abilities, and post it on the forum, I am sure there will be a bunch of people who would be grateful to already have documentation, as well as there would be people willing to upload it to Github for you. You would then NEVER have to use that awefull, worthless, good-for-nothing website again...

This way we could FINALLY stop discussing how much we hate/like wiki/GitHub and could finally start making progress towards creating better documentation.

I hope you guys change your mind about not writing docs based on which site they're hosted on, since we could definitely use any and all help patching the holes in the docs. You guys seems like knowledgable people, and I think you could definitely make positive contributions. Would be sad to see you refusing that over a website...

2 Likes
45

I'm waiting for the refactor promised and the easy links and the vastly increased list of approvers of doc changes. I think these initiatives will help. These changes wikify the documentation system somewhat, like it or not. I do think that if helpful doc contributions are not fairly quickly approved then contributions might dry up as quickly as they might now start up.

The issue is very far from being confined to my missing contributions or those of @spydrop (for whom I do not speak and v.v.). As an aside my problem is that, just like Dick Cheney, I know some of the things I don't know but I don't know all the things I don't know. I can't document what I don't know and I can't list what I don't know I don't know. I am however helping to build the list of things which I know I don't know in the thread provided for that purpose by @wgbartley. I note I am one of very few in contributing so far things needing documentation to that list.

No, the problem is all the advice and knowledge dispensed in most forum topics over months which has never found its way into the documentation despite the supposed ease of that process and claimed ideal nature of the tools provided. It is this documentation which is missing and for which github commits have not been done. It is that advice, that knowledge, and those tips which ought to be being contributed. It's all very easy, I'm told. It is those contributions which need chasing, @Moors7.

46

There’s not much I can add to that. I’d have to agree with everything you say here. I’m also looking forward to the technical improvements of the docs, as mentioned by Zach. I’m also not against Wikifying it, as long as the guys held accountable for the docs have a chance to browse through it before it gets ‘official’. I wasn’t trying to say you HAVE to write documentation. What I was trying to say was, if you’re willing to write docs for a Wiki (or a not-GitHub) system, that it would be a shame if you wouldn’t want to write it because it wasn’t on there.
If you’re capable and willing to write docs, you could help out without GitHub, as I’m sure there are people willing to upload it for you, if you were to post it ‘raw’ elsewhere.
I do appreciate the effort you’re putting into finding stuff that has yet to be documented. It’s just as important as documenting it, and someone has to do it. If you can’t or won’t write docs for Git, then this is a real nice alternative, for which I’d like to sincerely thank you!
Most importantly I was trying to say that if you were willing to write docs, you shouldn’t let the fact that it’s on GitHub stop you. Write it anywhere you’d like to, and then pass it on. That’s what Open source is all about, I believe. Working together to make things better. You might be able to write real nice documentation, and someone else may be really efficient in posting stuff on GitHub. If you can work together, both would profit and could complement each other.

According to Wikipedia :wink::

Open-source code is typically created as a collaborative effort in which programmers improve upon the code and share the changes within the community.

So yeah, my suggestion is that we all work together, so that we may all benefit. Let’s ‘collaborate’, and help each other out wherever someone might find difficulties. So far everybody here has been really helpful, the elites in particular. If you find difficulties working with GitHub, then don’t fear to ask for help. The “Documentation Needs” is a nice step in the right direction so far.

1 Like
47

When it soon becomes almost as easy to contribute a doc change as it is to comment here to a forum post, there will be plenty of doc changes contributed, and also from me.

3 Likes
48

Looking forward to that, you seem like a clever enough guy to make some really useful contributions! Would be awfully nice to have you helping out, things would only get better :slight_smile:

2 Likes
49

Closing this thread due to another Documentation thread that was started where we are being constructive and capturing the deficiencies over here:

Please go contribute there no matter your skill or editor preference! :blue_heart: :spark:

4 Likes