90
edits
Changes
Summer of Code/2018/Making a Beginner Guide (view source)
Revision as of 05:27, 20 March 2018
, 05:27, 20 March 2018→Risks
* '''Risk [[#1]]: your beginner guide does not help a beginner'''
* '''Risk [[#1]]: your beginner guide does not help a beginner'''
::* Currently Sugar Labs has multiple newcomer guides in the forms of a book, [https://wiki.sugarlabs.org/go/Documentation_Team Sugar Wiki], and [https://github.com/sugarlabs/sugar-docs sugardoc], [https://wiki.sugarlabs.org/go/Google_Code_In_2017/background GCI Starter].
::* Currently Sugar Labs has multiple newcomer guides in the forms of a book, [https://wiki.sugarlabs.org/go/Documentation_Team Sugar Wiki], and [https://github.com/sugarlabs/sugar-docs sugardoc], [https://wiki.sugarlabs.org/go/Google_Code_In_2017/background GCI Starter].
::* I will try to bring the content of all these resources at a single place which would be sugardoc because we would be utilizing [http://www.sphinx-doc.org/en/master/ sphinx] to convert markdown to HTML, pdf format. We have another alternative to display content on our dashboard using [http://docs.readthedocs.io/en/latest/embed.html ReadtheDoc Embed] feature.
::* I will try to bring the content of all these resources at a single place which would be sugardoc because we would be utilizing [http://www.sphinx-doc.org/en/master/ sphinx] with [http://www.sphinx-doc.org/en/stable/theming.html classic] to convert markdown to HTML, pdf format. We have another alternative to display content on our dashboard using [http://docs.readthedocs.io/en/latest/embed.html ReadtheDoc Embed] feature.
::* Now instead of having multiple newcomer guide resources, we can add all the resources in one place and remove other resources of newcomer guide.
::* Now instead of having multiple newcomer guide resources, we can add all the resources in one place and remove other resources of newcomer guide.
::* I have large student community at my college. I have a thought of organizing Sugar Labs online seminar, where we can guide them about Open Source contribution, and direct them to the newcomer guide.
::* I have large student community at my college. I have a thought of organizing Sugar Labs online seminar, where we can guide them about Open Source contribution, and direct them to the newcomer guide.
* '''Risk [[#2]]; Beginner guide conflicts with other information'''
* '''Risk [[#2]]; Beginner guide conflicts with other information'''
::* Those formats will be used which are generally acceptable and maintained by everyone.
::* Markdown would be utilized.
::* Only open-source software and technologies like [https://github.com/twbs Bootstrap], [https://github.com/angular Angular], [https://github.com/nodejs NodeJs], [https://github.com/angular/material2 Material] etc will be used.
::* Throughout the development only open-source software and technologies like [https://github.com/twbs Bootstrap], [https://github.com/angular Angular], [https://github.com/nodejs NodeJs], [https://github.com/angular/material2 Material] etc will be used.
::* As discussed in the previous risk, [http://www.sphinx-doc.org/en/master/ sphinx] engine will be used to convert our markdown of sugardoc to HTML content of our dashboard's newcomer guide, Sphinx also provide the feature to covert the documentation in the pdf format.
::* To convert Html files to markdown [https://domchristie.github.io/turndown/ domchristie.github.io]
::* Remove information from the current existing guide and put the link to new guide at those places and linked properly for proper navigation.
::* Remove information from the current existing guide and put the link to new guide at those places and linked properly for proper navigation.
* '''Risk [[#3]]; your beginner guide is abandoned soon after publishing'''
* '''Risk [[#3]]; your beginner guide is abandoned soon after publishing'''
::* I want to work on this project even after GSoC period gets over. I see a huge possibility of exploration of Sugarbot and I will be always there for updation of the newcomer Guide and keep working on Sugarbot to make things automated and easy.
::* I want to work on this project even after GSoC period gets over. I see a huge possibility of exploration of Sugarbot and I will be always there for updation of the newcomer Guide and keep working on Sugarbot to make things automated and easy.
::* As there is the only one source of newcomer documentation which is sugar doc and markdown is used there, so it will be easy for everyone to update it on Github repository.We will also add a page with the contributor on Sugar Doc where we can list the name of developers who contributed to Sugardoc and other projects. Also as it will be the only source documentation so the risk of "Rarely do new people begin to edit" is also removed. The developers can showcase their contribution on that page so it is sort of social reward for them by Sugarlabs.
::* As for the contributor who is not comfortable with Github, a part about getting started with Github will also be there in the newcomer guide. Link to basic syntax of https://www.markdowntutorial.com/ and [https://guides.github.com/activities/hello-world/ GitHub] and such links will also be there. There will also be badges when you complete this part. It will attract the contributor to learn Github and its task. After there learning they can also contribute to Sugarlabs through Github.
The root cause is that people vary in their comfort level with specific
tools or sources. For example, we still have a valuable contributor
who will not use GitHub no matter how hard we try to help them.
===Timeline===
===Timeline===