Documentation, again

General
21

Pub 777, your list IS important since as a more advanced user you are more acutely aware of the weak areas of the documentation. Those areas you mentioned are a good start!

Trust me when I say that no one is “withholding” nuggets of knowledge. It’s more a matter of getting organized and realizing that open source doesn’t mean “self documenting”. As the Spark Team grows and settles as a nascent company they will get it right. We all want the same thing and your comments and contributions are always greatly appreciated. :slight_smile:

1 Like
22

One thing which is unclear to even “advanced” users (I am struggling and I am flattered) is who is who. Who is helping out from the goodness of their hearts? Who is part of Spark and who is not?

1 Like
23

That was pretty much where I was going as well. If you’d want to contribute to the docs you’d have to write up some text anyway. Since we live in the digital age, it’s a matter of copy/pasting that text when it’s done.
Irrelevant of where the docs are going to be posted, someone, somewhere, will have to write them.
I am in no way saying that the current situation is superior to a Wiki. What I do think is positive, is the fact that the people who work on developing the Spark get a chance to proofread the material before publishing. They’re much more experienced (or up-to-date) and could therefor have a positive impact on what’s being written.

Im not so much defending the current GitHub system, as I am defending the idea behind it; people can write up documentation, and the elites/moderators/Spark check them. If they’re happy with it, then they can publish it. I like the idea of having a double check in order to decrease the chance of false information ending up on, what would then be, the official documentation.

It’d be the same as if John Doe wrote up a fix for your printer on a wiki, but yeah, in the end it turned out it John Doe was a bored twelve year old, who barely knew what a printer looked like. Now if Samsung would have had the ability to proofread it, they could have prevented, or corrected it. They might have not had the time to write up their own docs, but could then make a useful contribution to someone else’s docs by validating them.

“Preventing is better than healing” would apply here as well. You’re saying that’s it’s not ideal that documentation is written after development, which I can’t disagree with. I’m saying it’s less than ideal to correct mistakes after publishing.

What would be awfully nice is a change log of sorts. I too, am sometimes struggling to find that one little feature amongst all those that are not yet documented. If we could have a list somewhere with a 2-3 line description of (preferably) all functions, than that alone would save a lot of headaches. People could then start contributing towards those undocumented features, which could then build up to some nice documentation. This way people can be made aware of new functions, and they can help writing up docs, saving the Spark team some work.
This list could perhaps serve as a temporary solution for not yet completed docs; people know the functions exist, with a short description of what it does. They could then ask the more experienced people on the forum, while the docs are being written.

If you could limit wiki submissions to validated contributors (people with two validated posts for example) then I guess it could be a viable system.
I’d much rather not work on something due to lack of docs, than be frustrated to no end because the docs are faulty.

Differentiating who is who can be done by checking their “titles”. Spark employees have fancy titles such as “senior software developer”, whereas non-Spark people have got “Spark elite” to indicate that they’ve made notable effort in the Spark-scene.

24

I have slept in 20-something hours, so I’m thinking out loud here. What if we came up with a sort of interim middle ground? Maybe the less GitHub-inclined members wishing to contribute documentation do so as a forum topic? Create a topic like “Documentation: UDP Stinks” and contribute the content for the documentation. Then someone can volunteer to put it in the documentation for you. I can recall discussions around a lot of these documentation sticking points, but I can’t remember any of them directly!

I’m not nearly as technically inclined as many around here, so I want to do my part to pitch in wherever I can, and this looks like a good place for it. I know how to use GitHub, and I know how to use copy+paste! Let me help take some of that burden of so that people can get back to what they’re doing that I can’t do! Heck, I’ll probably learn something along the way.

I know it’s not ideal, but I also know that the Spark Team is traveling back to HQ this week and then some turn around and go straight to another conference next week! Maybe we can give it a shot for a week or two so that, at the very least, we can get the missing documentation in place in the current system. That way, if a decision is made to move to a different system, everything will still be in one place and ready to move.

3 Likes
25

So what most are saying is business as usual and people need to rely on forum support ? You kwow, I do know how to read instructions and in the forum I get instructions from everyone; every which way; try this it might work; this guy at this link seems to have a great approach and just maybe a spark elite will chime in on my idea - and to be fair they usually do !

However, 10 million wikis are being used world wide and for a very good reason. Because official ways limit development.

1 Like
26

I think you forgot the link. :wink:

1 Like
27

Hey there, hi there, ho there from Spark HQ - We were all tracking on this thread while out at MakerFaire, and of course documentation best practices are supremely important to us & everyone in the Community. Just wanted to reach out and acknowledge that all of this feedback is extremely valuable, and Spark can and will improve documentation processes to be more helpful, concise and clear to all levels of users. Thanks very much for all of the input and solutions!

3 Likes
28

Hey All,

I just wanted to echo this, and it’s been said in one way or another, but our documentation is editable / forkable right on the github page (no command line stuff needed).

Not to be corny, but a wiki is defined as a website that allows collaborative editing of its content and structure by its users. We certainly intend to encourage collaborative editing, anyone is free to edit the documentation by sending a pull request, which is how many open source projects collaborate now-a-days. :slight_smile:

Github has a concise guide to sending a pull request here: https://help.github.com/articles/creating-a-pull-request

edit: I think any resistance to a Wiki is just a matter of time on our end. We want to make sure the docs are as accurate and helpful as possible. A wiki would be a whole new site / structure that would be difficult / very time consuming to maintain and monitor, and would have to be actively kept in sync with the main site documentation.

Thanks,
David

3 Likes
29

re-reading through your post again, I wanted to jump in:

We agree, the CLI needs a lot more documentation! I’m working on a dedicated docs page for the CLI which I think will be really helpful. We’re also re-mapping the CLI commands to be easier to use, but I’m working hard to make sure the old commands can still be used as well.

Thanks!
David

2 Likes
30

I might be the exception, but I often get annoyed with wikis. They are unstructured by nature (unless you put a lot of effort into establishing a structure from the start), which generally makes it hard to find what you want by normal navigation. Also, there are as many different flavors of wiki markup as there are flavors of wiki, so I always have to pull up the markup reference. And even when the wiki has a WYSIWYG, it usually doesn’t include functions for all of the features I often need when editing technical documentation. And as for Wikipedia staying relatively spam-free, that’s mostly thanks to some complicated rules about who can edit which pages, and an army of dedicated community volunteers who actively monitor the site.

While using GitHub for docs might not be the easiest thing for everyone to use, I think a fairly high percentage of Spark users either already use it, or are capable of picking it up quickly. As noted previously, Markdown is quite intuitive for most editing needs, and you can do everything in the browser just fine.

I’m not saying that a wiki is a bad idea, or that I wouldn’t use it if the Spark team decided to move to that. I’m just saying that a wiki is not necessarily a “better” solution for everyone.

I’m all for better documentation. Trust me, there are things I’ve looked for that don’t seem to be there (yet). And if I wasn’t so busy at my day job right now, I probably already would have contributed to the docs. And whether we stick with GitHub or switch to something else, I probably will at some point.

4 Likes
31

The undeniable advantage of the wiki is that it removes the bottleneck in the submit-review-approve-publish cycle. You obtain instant gratification at seeing what you wrote immediately. That’s the reward necessary to encourage documentation contributions. The arguments I see advanced here against wikis include ones of tidiness over content. All the other so-called disadvantages of wikis over other documentation systems exist in those other systems in other guises, to greater or lesser extents. For the time beng we will continue with the forum as our primary documentation reference, with all the disadvantages of that: The same problem addressed in many disparate threads, bad advice remaining uncorrected not in place thus forcing one to read all the comments to a thread. The best advice often being in two comments, neither quite right, but this is not obvious to the average reader, and those who know often shying away from correcting the great and the good. One’s faith in human nature, the way one believes society best works is, in my view, demonstrated by one’s attitude to wikis. Authoritarians hate wikis, anarchists love them :slight_smile:

32

Since this is turning into a “I (dis)like wikis for this/that reason”, I thought working towards a solution might be nicer…
Continuing from my idea that a ‘news/changelog’ page would be nice;
How about making a category “documentation”? :spark: and the elites could pin a topic there with all features which have yet to be documented, which can be updated accordingly. As soon as documentation is available, a link could be posted.
It seems to my like this has several advantages (for the time being):
-You have an overview of all features/updates.
-One could then start writing documentation, and be instantly gratified by posting it in said category.
-Your docs are immediately open to the public, and can be made use of, elimination frustration of lacking documentation.
-Documentation is concentrated, it ensures people can find it easier than browsing through random topics, in which information is spread.
-This gives :spark: and elites an easy possibility to edit/correct your post, thus eliminating any mistakes. Heck, anybody could read it and make contributions to it, before it ends up on the official docs. This makes sure everybody can already start working with the new features as a sort of “beta”, after which official docs will be updates as soon as the documentation is sufficiently written.
-If they’re happy with it, it can be updated on the github/docs page.
-People can ask questions, and make comments about the docs. This can sort of turn into a FAQ about said documentation, which may only improve the quality. This way, all questions toward those specific documentation are also concentrated on one topic, eliminating the need to browse through the entire forum, or creating the need to open yet another topic, preventing duplicates as well (RGB control for example).
-If in the future the docs change to another system, it’s easier transferring them.
-If you do not like working with Git, simply don’t know how, or don’t want to learn yet another thing, you could still make useful contributions to the docs.

Like I’ve said before, the docs need to be written either way, whether you’re going to post them to a wiki or to Git. Since we don’t have a wiki, and people (appearantly) don’t like Git, there needs to be a place where these docs can be published. Said category might be a nice solution for that. It’s a compromise between the immediacy availability and user editable data of a wiki, and the ability to be validated by the “pro’s”.

This is just an idea, but I thought it might be useful. At this rate we’re mainly discussing how useful a wiki might be, but in the meantime we’re still ‘stuck’ with problems it seems. So as long as it’s not clear what’s going to happen with the docs, I thought it might be helpful to have an intermediary solution, hence this post.

4 Likes
33

I agree with @Moors7. Instead of debating the merits of wiki vs whatever, let’s focus on what’s in place now. I think the original concept of this thread was to improve the documentation content, not to trash talk everyone’s various opinions about the documentation system. We can all agree that it the system needs improvement!

Let’s be constructive and productive and move forward!

2 Likes
34

This is getting boring since we all VIGOROUSLY and fundamentally AGREE on the same things. What we need now (yes I am repeating what others have said already) is to stop yapping about how and start focusing on content by attacking what is missing in the documentation once and for all. Later, we can debate the merits of how to present it.

@psb777 et al, I challenge you to start identifying specific areas where documentation is lacking, in your opinion, and either contribute text or communicate those shortcomings in a clear, effective and constructive way. If we had spent as much time on actually FIXING the documentation as we did yapping about where it should be, the discussion would be largely academic now. I want to say something about rubber, a meeting and a road but I think we all get the point. :wink:

4 Likes
35

I have already listed some areas needing attention, and at your request @peekay123, in this thread. I agree it’s better if I would contribute some documentation but it is not true to say that identifying areas which are deficient is not valuable in itself.

In several other threads I have pleaded for more documentation, and the questions have largely gone unanswered. I suppose I could answer some of those questions myself, were I prepared to RTF source code. That everyone here must do that cannot be the intention of the Spark team.

To my mind this all comes down to how successful Spark is going to be. The most complete up to date documentation is found here, in the forum, not in the documentation! F’rinstance the recently answered Q of mine: What are the chars permitted in the parameter to a Spark.function() function? The location of the answer is not ideal. It is not ideal. I hope that someone is busy updating the all-singing all-dancing github. If so the answer will be in the doc web pages some weeks from now. But hardly any of all the other answers here, in the forum, have found there way into github.

36

Aha! Good point @psb777! Given the speed of development these days, I am not surprised, as you say, that stuff in the forum is slow to make it to the documentation. So, that is our target - to the best of our abilities, bring key information from the forum to the “official” documentation or a least a link to the forum topic.

Oh, and I have not forgotten your requests. The Elites do have a life outside of this forum so things may not happen as quickly as we want. They will nonetheless happen so thank you ahead of time for your patience and any contributions you can make.

1 Like
37

I think @peekay123’s point was to help compile a list of known deficient documentation into a concise list. Much like the documentation, the requests for documentation also gets lost in forum threads. To that end, let’s stop postulating over documentation and start writing it instead.

I’m currently working on a way for us to “tag” posts that either request additional documentation or supply additional documentation that should be included in the official docs.

1 Like
38

Where will be the location of the concise list?

39

@pbs777, the Elites a compiling a list but I believe making this available to all members will be done. Stay tuned.

40

Let's start with this one -- Documentation Needs