Fix broken links in doc page

[khanstark]

Referring to issue #108 , fixes the Component Documentation link and remove some typo. @walterbender @davelab6 to review.

[quozl]

Your branch is out of date, please merge or rebase against our master.

Other problems with your pull request;

• [ ] your docs.md change was not a typo, and you have disturbed the line wrapping, please undo.

• [ ] the link you have added for components documentation is not documentation, so remove the link rather than add a bad link,

• [ ] your change to what-can-i-do.md is wrong; because it links to web site back to the GitHub repository; the web site should stand alone; instead you should use the Markdown embedded link method

* [Write a new sugar activity](activity.md.html)

You can see an example of that method in index.md.

[khanstark]

I 'll make changes and create new PR.

[khanstark]

@quozl I was going through the repos and trying to understand your suggestions...here's what I don't understand--

• regarding docs.md , should the color be detailed as rgb(255,255,0) or (rgb 255,255,0)?
• I tried to redirect the components documentation link to components page itself since there is no stand alone page for documentation. I guesss we should remove that link from index.md itself.
• the link `Write a new sugar activity` looks confusing to me since we don't know which activity we are talking about (Desktop, web or android? )or where should we redirect the page?

We need to tidy up the documentation page. Thanks!

[quozl]

• regarding docs.md , should the color be detailed as rgb(255,255,0) or (rgb 255,255,0)?

Existing text is fine. What you propose could be interpreted as a function call. I don't see why you would want to do that. The step looks like workflow for The Gimp, which can accept colours in various forms. A more common form would be the hex triplet, such as #ffff00. In your commit message, you didn't say why you thought it should be changed, and you also changed the wrapping of the line, which made it hard to be sure what you had changed. This lowered my confidence in your change.

• I tried to redirect the components documentation link to components page itself since there is no stand alone page for documentation. I guesss(sic) we should remove that link from index.md itself.

Where is documentation of components for web activity development? Until there is documentation, the link should be removed rather than add a link to a page (github.com/sugarlabs/sugar-web) which has no documentation.

• the link Write a new sugar activity looks confusing to me since we don't know which activity we are talking about (Desktop, web or android? )or where should we redirect the page?

I'm surprised. It doesn't look confusing to me. I know exactly what the text and link mean. Desktop activities are the most mature and documented. I would not want to invite new collaborators to work on web or Android activities given the low quality of documentation for those paths. You might add the word Desktop if you like, but the term (desktop activity) is really only used here in sugar-docs; these activities are more frequently known as Python or Gtk+ activities.

[khanstark]

How can someone interpret rgb(x,y,z) as a function call? Its one of most commonly used syntax amongst web developers for providing colors. On the contrary, rgb x,y,z looks unprofessional to me.

Anyways that was only my suggestion and I m no one to force them. If u dont want it to look that way, it's absolutely fine.

So I guess we can only change the text of Write a new sugar activity to Write a new desktop sugar activity to be more comprehensible.

Discard other suggestions.

Thanks!

[quozl]

The name followed by open parenthesis represents a function call in many languages, and for the colour specification in CSS language. Neither use is anticipated in the context, which is about image editing.

That's interesting that you think it is commonly used. Do you have a citation for commonly used syntaxes among web developers? To check, I've scanned our mailing list archives by regular expression, which shows the pattern "RGB(n" is more frequent (qty 1) than "RGB n" (qty 0). But this does not seem statistically meaningful. If you can give me a reference, I'll happily change my mind.

I'm only one reviewer. That you have no balance against my review is because nobody else is speaking up. Do you have any other reviewer in mind that you can ask?

Discard other suggestions.

But I would like to see https://github.com/sugarlabs/sugar-docs/issues/108 fixed. :grin:

[khanstark]

@quozl Its amusing that u r asking for a citation for commonly used syntaxes....!! I m sure people contributing here would be expert in many languages, that they r qualified enough for understanding what does RGB stand for, and in what context it's been used there!

Nevertheless, To resolve #108 , for now, we can remove that link Components documentation, until & unless we get its full stand alone doc written.

[quozl]

Both the original format and the format you propose seem equally to describe the colour yellow to experts, but we have had a large number of non-expert students lately and I don't see why we should confuse them with something that looks like a function call or CSS when the context is image editing.

[khanstark]

@quizol what do u propose for that Components documentation issue?

[quozl]

I wish there was better documentation for the JavaScript activity type.

It is unfair that the Python activities are so easy to write because of the multiple documentation sources; both developer.sugarlabs.org, our API documentation https://developer.sugarlabs.org/sugar3/ and James Simmons book Make Your Own Sugar Activities. Supporting those sources are good examples, bad examples, the Python GI API Reference, and Python language references.

We have on developer.sugarlabs.org some pages that explain writing of JavaScript activities, but I think there is a need for an API reference of some sort.

While there isn't one, Components documentation should be removed.

[quozl]

e195d58