Documentation, again

General
1

Continuing the discussion from Documentation system?:

I’m not one who thinks that it is OK to push ahead on the development without there being adequate documentation. I think this creates chaos and confusion and encourages a two-tier user base, the experts and the newbies. There always will be experts, of course, but the route to become one can’t be endless experimentation and having to resort to reading the underlying code. The knowledge drawbridge is being lifted, a cathedral is being constructed. No, break down the walls, make it easier to contribute to the docs, require developers to fully document what they release.

I don’t like the idea of using github so as to allow users to contribute to the docs. Github has its uses but it is not intended for easy documentation. Neophytes, newbies, the non “Elite” ordinary folk will be dissuaded from contributing. Github is for software patches and releases, primarily. What we need is a documentation Wiki.

3 Likes
2

That sounds good and I guess we are always open to making things better!

I’m not sure if Wiki will be better that way since anyone and everyone can make changes and we will need moderation to ensure we have it the best way for beginners to get started!

Github sounds like an awesome tool for this matter as we can check the PR and revert if there’s something we need to work on.

How about telling us the No. 1 most important factor to use a Wiki VS github? :smiley:

1 Like
3

@kennethlimcp, why don’t YOU give the No. 1 most important factor to use Github vs a Wiki?

I don’t know how to use Github and I don’t want to learn. The average Spark Core user is not going to be github literate. However there will be many capable of contributing to documentation who will never need or want to learn github. I am one of those, potentially.

As to your other so very questionable point if it works for Wikipedia it will work here. I do NOT see vandalism as being an issue - doubtless a login will be required.

Already there is lots of duplicate, near-duplicate, usually incomplete and sometimes even incorrect advice here on Forum. Github is for software, the forum is for chats, a Wiki will be for collaborative construction of reference documentation, and is a suitable tool for same, unlike this forum or github.

The status quo is poor and inadequate docs which it is difficult to access and near-impossible to amend. I would be happy with github-based documentation or docs in any format if it were adequate. It is not.

1 Like
4

I will give but two examples of poor documentation

UDP is broken, that it is broken is well established, workarounds are possible in some situations, and a bug report has even been raised and recently this has been chased by another user seeking resolution. Lots has been written about this issue. Yet, the documentation does not reflect this, and it so easily could: A newbie to Spark but perhaps an experienced network programmer will read the docs, write his app, think he has made programming mistakes, finally come to the forum, and the high priests will emerge from the cathedral to inform him yes, there is a bug, there are several bugs, Spark UDP doesn’t work as UDP works elsewhere. If the docs were in a Wiki the frustrated programmer would have known this.

I have recently posted questions re the publish-subscribe semantics and protocol. This should be in the docs. Instead all we get is just the function names and the arguments and a few short sentences. If the doc was in a Wiki I could add those questions to the page(s) for the functions. And then @kennethlimcp or another anointee could replace the questions with the answers. And should the answers need clarification or improvement or if they are plain wrong they can be fixed, perhaps even by the github-ignorant me, when I find out how it really works. Failing which I will correct spelling mistakes because that too is useful.

5

No. 1 factor :smiley:

Have fun!

6

@psb777,

I totally agree that a Wiki is needed; an officially supported Wiki !

I see an added benefit to using a Wiki and that would be to give users a way of providing documentation of their own projects instead of having to setup websites or use categories in this forum that do not appropriately reflect their project.

GREAT IDEA ! Spark Core Team - “Can we have an Officially Supported Wiki ?”

2 Likes
7

i’m with kenneth, github is where the documentation already is and where it needs to stay. we just need the development team to be monitoring pull requests from users.

much better than a wiki that anyone can edit with any old crud that isn’t even accurate. also if its a wiki i fear it will use the same rubbish software that the website and forum use.

8

I find github for the documentation to be fine and easy to use.

  • The doc is already in a wiki-like markdown so it is easy to edit
  • You can use the editor on github in a web browser to make changes right on the web and github forks and handles pull requests easily
  • I am sure it is easier to curate and put on the web server for the Spark team–github makes that part easy for them

I like wikis and wikis certainly have their place for collaboration. In fact, github has wikis built-in that the Spark team uses sometimes.

The doc is behind the current code, but sometimes for good reasons, like the team wants to change the code in the near future and doesn’t want to doc it twice–the WiFi and Cloud control is a good example of this. The forum acts a way to talk about today’s work-around that will be fixed, possibly differently, and doc’ed in the future.

I think you also have to understand that the Spark team has business goals they are trying to achieve. If a wiki fits their goals, that’s great, but if it doesn’t for some reason, then I think you have to work in their framework or start your own.

For projects, there is spark.hackster.io which already has a bunch of great project write-ups.

9

When all you have is a hammer …

Look, I’m in favour of whatever works. Github Is bring used now but it is not attracting any documentation contributions. It is not working. That the holy scrolls can only be written by the high priests might not be true but in effect the congregation is not encouraged to modernise the liturgy.

10

We have 526 Commits for spark-docs and going strong!

If you guys want to contribute, the web github does it just fine!

I did an entire translation using the chrome browser!!!

Hope to see more PR from everyone :slight_smile:

2 Likes
11

How many commits from ordinary users? And its 10000 commits you should be looking for.

1 Like
12

I honestly hope to keep it as low as possible which would mean that we got the documentations well done up! :smiley:

13

By your measure the docs are finished, perfect.

14

Lets not get childish folks, if you’ve got some documentation to contribute then do it, don’t argue about it.

5 Likes
15

As I sometimes do I damage my own point by overstating it, thus allowing myself to be contradicted by the citing of 500 contributions almost entirely all of those not by ordinary users. As is acknowledged almost by everyone, there are large gaps in the docs. Some of the docs is good, other info is perfunctory. Some is plain missing. It does seem some here are not in favour of even discussing the possibility of a system which would allow and encourage documentation contribution.

16

I think we can all agree that the current state of the docs is not ideal, for anybody. The elites know what’s going on and are up to date due to their active roles. A lot of other people don’t know what they’re doing, due to a lack of proper documentation. I must really praise the elites for being so helpful, and patient with everybody on the forum, they help out where and whenever they can!
And even if most of the commits come from the elites, so what? They know whats up, and create documentation accordingly. Most of them have been following the Spark since the very beginning, and thus know a lot more about it than ‘normal’ users. Besides that, they really spend A LOT of their time on the Spark. It therefor only seems logical that someone who knows the product better, spends more time on it, and is more experienced makes more contributions as a ‘normal’ user would.

But to recap; you’d like to have a wiki where validated users (you mentioned a login) could upload their documentation, which would then be added for everyone to use.
Isn’t that similar to the setup we’ve got right now. As it stands, everybody can contribute by writing up their own docs, and then submit them to Github. They are then proofread by the nice :spark:ies, after which they can be published.

The only difference I can see is that with a wiki, the Spark team wouldn’t validate the submissions beforehand. Personally I think it’s wise to let them check it, since they’re the people who built the thing, and therefor should know it inside out. This is in contrast to ‘normal’ people, who can only pull the information out of their experiences with it. I’m not saying that’s worse, but a lot of confusion might be prevented if you’d let Spark check it before publishing. If they have to do so afterwards, there could be some confusion due to possible inaccurate information on said wiki.

If anybody wants to help out and write additional documentation, there wil be one very important thing they’d have to do. This would be “actually writing it”. The only difference would be where you’d upload it; Github vs Wiki.

At the moment it sounds like you really want to push through on creating a wiki. At the moment that would only make a bigger mess since information would get spread to two sources, one being ‘officially supported’, one being community based. If you want Spark to check that as well, it would only create an additional workload.
So yeah, I’m not too fond of the current docs as they are, but I’m not sure if a wiki would be the answer either.

2 Likes
17

I think it would be better were the official documentation a wiki, that the current repository (but not the info) should be abandoned, and that the documentation should be collaboratively generated. Unreviewed and temporarily incorrect documentation is better than static once-correct but incomplete or or incorrect or missing documentation - the current position. I think the submit-review-approve-publish cycle is unnecessary and to no purpose. Better the immediacy of live edits to a wiki - that’s the way to encourage contributions.

18

An example of documentation not being complete but the missing text exists and has been referred to several times very helpfully here by some but that text has not been committed github: The extra undocumented functions available just by including math.h - still this is not in the firmware documentation. In a Mediawiki (e.g. Wikipedia) style of wiki it would be easy even for the neophyte Spark user who asked the question to add the answer to the docs. In the current doc system one has to ask why has this not been documented, if it is so easy to do so? Just one example.

19

Pub 777, I agree with you on the state of the documentation though right now I don’t much care where it sits. We can figure that out later.

In the meantime can you tell me some of the “hot spots” that need to be fixed and I’ll do my best to mobilize folks to get it done. If you can contribute as well, it would be greatly appreciated.

Once we have decent documentation, then that will be the time to discuss the most effective tool for maintaining it.

3 Likes
20

@peekay123, I appreciate your constructive approach but there is a cart and horse thing happening here, not a chicken and egg! Once the documentation is better it will not need to be improved, and the mechanism for getting it to that state will not be needed :slight_smile: That would suit me 100% fine, of course!

I asked here a few days ago about the publish/subscribe protocol and semantics.

Sometime ago I noted here too the firmware libraries and functions available just by adding an include - not an external library - are not clear and not documented. math.h is an example, I guess there are others. For all I know there could be extra functions available without even the need to add an include. We know the docs are incomplete but we cannot know just how incomplete they are! What is the complete list? I’ve asked this before. Do I need to wait for the existence of something I need to be revealed on the forum?

I think the flaws in UDP would be best noted in the UDP reference section of the firmware manual. Where else could be better? That some functions do not work as described and certainly not as would be expected is more than just a bug, and I guess this won’t be fixed soon. In the interim?

Has the spark cli cloud compile changes where multiple files can be named, and/or exclusion/inclusion lists can be used, gone live? If so, how am I supposed to know this? [Half a dozen Spark Elites jump up and down and say Github.]

But, really, my list is not of overriding importance even to me, as next week I’ll be puzzling over something unanticipated. I am simply agitating for better documentation all round. In doing so I do not mean to detract from what is excellent about the Spark Core. It can’t be the case that some would prefer their secret knowledge is NOT disseminated, or can it? It sometimes seems that it is being rationed. If you want to know you need to ask a favour. Those who know are not documenting what they know. It cannot be the case that the primary documentation reference becomes the forum! I guess by writing such I might find my share of favours drying up, but I didn’t come here to make friends [evidently! say half a dozen].

I bought a Samsung printer recently. It did not work how it was described [Cloud Print]. The firmware patch process did not work from any o/s as promised. The helpdesk was helpful enough. I got it working after lots of unnecessary struggle. The help desk won’t be made redundant - they still haven’t updated their online advice. If they ran a wiki I would have updated it on the fly, while I was there. I’m a bit pissed-off with Samsung. Nice printer!

2 Likes