Project Details- Why && How

This post describes the Why and How of the migration process.

WHY?

The primary objective of any product should be to help its users. And Sugar is no exception.

The Sugar Desktop Environment (along with its Apps(called Activities)) is used by school students in over 40 countries. Most of them with limited access to Internet.

Thus it is important and essential to make as many resources directly available to users; as possible, reducing their dependence on external factors like the internet.

Over the years; Sugar Labs(the organization committed to maintain/develop Sugar and its derivatives) have been using its wiki(at https://wiki.sugarlabs.org/go/Activities) to maintain documentation(both developer and user) of different activities.

But as new, better, easy-to-use tools for collaboration came up, the shift to GitHub was inevitable.

Migrating the documentation of activities, from the wiki to the activity source repositories at github/sugarlabs and in parallel to the help-activity, has a lot of benefits:

roughly stating: [help is an activity which provides support about using sugar and its different activities]

  • It reduces maintenance efforts
  • User-documentation moved to the help-activity could just be downloaded once, and then read whenever needed. Eliminating the need to have persistent internet connectivity(which is often not available).
  • Contextual help (by alt+shift+h) from within another activity could also be made available, if the documentation is at help-activity.
  • Developer documentation about an activity, if kept at the same place with its source-code in the repository; would help developers/maintainers a lot. (they could be read and updated easily; without needing to visit a different link to the wiki)
  • also, GitHub is the world’s largest software development platform(according to Stackoverflow 2018 developer survey report). Thus, it surely is easy-to-adapt and has the potential to attract more developers into the community(which we need as much as anything).

HOW?

1
2
3
4
5
6
7
8
9

  for each activity documentation page to migrate:

      check(manually by reading) if it contains user-documentation/developer-documentation/both:
        if user-documentation:
            to be moved into [help-activity](https://github.com/godiard/help-activity)
        else if developer-documentation:
            to be moved into activity source repository(as README.md)
        else
            divide the content. and move accordingly

Once we know, where a page needs to be moved, A script runs as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13

  pagename = {name-of-page-to-migrate}

  # with the help of [Mediawiki API](https://www.mediawiki.org/wiki/API:Main_page)
  fetch wikitext from pagename
  fetch list of images/files used in pagename
  fetch all images/files in the list

  # with the help of [pandoc](https://pandoc.org/)
  convert wikitext to
  markdown
    if the pages is to be moved to source activity repository
  reStructured text
    if the page is to be moved to help-activity

Once the conversion is complete, I manually verify and fix some small details as needed. like; checking and fixing broken links (if any)

The same script is run for all the other pages, by just changing the ‘pagename’ parameter and customising the directories where the fetched images/files are needed to be stored inside a repository.

Order of Migration (Priority):

  1. Initial Documentation for most of the base-activities(Fructose) have already been migrated. I just need to check for consistencies and redirect the wiki-pages accordingly.

  2. I plan to migrate the tutorial pages for Turtle Art next. (because there are a lot of them)

  3. pages for other Activities which work with the latest Sugar.

  4. Rest of the pages.

Updated: