What Platform to Use?

[jdbcode]

I have been thinking about the documentation/tutorial platform. We originally thought we should just start out from a default GitHub Wiki so that collaboration could happen in traditional git style and new changes/content would auto-render.

However, there is a strange forking and rebinding process when trying to collaborate on a GitHub Wiki, and it also does not look very good.

I found a really good solution, I think. It is a Jekyll documentation theme that integrates with GitHub Pages, so is built from simple markdown and auto-renders whatever content is currently in the master branch of the repo. The theme has really handy sidenav and toc features. There is a little bit of work to set up the initial nav structure, but then can be easily added to. Content can be added and altered with pull requests.

• The Jekyll theme is here: https://pmarsceill.github.io/just-the-docs/
• I mocked up a doc page using it here: https://gee-community.github.io/GEE-Dev-Docs/
• The mocked up repo is here: https://github.com/gee-community/GEE-Dev-Docs

I think this is easier and looks better than the GitHub Wiki - it maybe does not have all the features of a more robust framework, but I think simplicity is paramount, and we get pretty much everything we need in markdown and some of the basic features of the Jekyll theme.

[schnjaso2]

sounds good to me! perhaps a bit trivial an issue, but it's good to square that away in the early goings, in order to better facilitate development in a unified front.

[rose-rs]

I would like to volunteer in the documentation. I am working to assess and monitor forest cover. I am an intermediate GEE user. This is a very desired step as I can see new GEE beginner's mail. I noticed that complex questions are addressed by GEE experts. the beginners (/ intermediate) may not be confident to put a mail at first place and after placing may not be redirected to the right part of GEE tutorial. As some may have started self-learning with a task to solve. searching in forums also becomes tricky due to the statement of the particular problem. This guide will be really helpful in that front.
If questions discussed in the 'GEE developers group' can also be linked in this document then it can be helpful too. ex. if I need to find area/stat of different group/class then I must find 'grouped reduction and zonal statistics'.
-Roshni

[jdbcode]

Welcome, Roshni - thanks for participating! To catch you up, there have been 3 major discussion threads:

1. What platform to use: want easy collaboration, easy content discovery, auto-render of content.

   Mostly decided on using GH-Pages with Just the Docs Jekyll theme - see https://github.com/gee-community/GEE-Dev-Docs. Raise any new issues/discussions on this repo.

2. How to organize content for discovery: flat vs hierarchy, search tags, pre-defined categories

   Leaning more toward a flat structure with "content tag" and title search. I'm still finding it helpful to have a couple of levels of hierarchy - see https://github.com/gee-community/GEE-Dev-Docs/blob/master/staging/staging.md

3. How to deliver content: static markdown, jupyter notebook, various interactive web-based offerings, link to EE JS script and include in-code commentary as comments.

   I don't think we need to dictate this too much, though I've found in working on staging.md that I like the format of having a few sentences to describe a script's operation or problem it solves and then link to its EE JS URL.

It looks like maybe you are new to GitHub? If so, that is great news! It would be really helpful to get your perspective on how we can make contributing content easy for people unfamiliar with forking, editing, and pull requests. An initial task you could help with is making an instructions page for how to add and edit content from the perspective of a new GitHub user. You could try adding some content to the staging.md file and also adding a new file to the staging folder. Both of these things can be done right from GitHub - see options for 'create new file' and 'upload files' in the upper right of GitHub folder pages and a pencil icon for GitHub file pages. As you do it think about what details are helpful to a new user and write them up in a .md file. If you need any assistance, start up an issue in the GEE-Dev-Docs repo and I'll help you out. Once you submit a change, one of the repo managers will need to merge it before it is visible - just FYI.