Hello all!
Thanks to the continuing assistance of Phil Rosenfield, last week I was able to get ahold of the WWT accounts on the service that we use to host most of our documentation, GitBook, and start straightening things out in the aftermath of their migration to “v2” of their platform. There was a lot to tackle, but I think that I got things to a much better place, and I’d like to report on where things now stand!
First of all, I have merged the old wwt-home and wwt-documentation meta-repositories on GitHub into what I am now dubbing the WWT Contributor Hub:
The intention is that this website will be, well, the hub for anyone who wants to contribute to the WWT project. Among other things it hosts the Code of Conduct, a brief Contributors’ Guide, and an index of all of our documentation.
Technical details: this is a GitHub Pages site. The source is in the GitHub repository named WorldWideTelescope/worldwidetelescope.github.io. The site content is generated statically using the Jekyll tool and the Just The Docs template. These are all very standard, GitHub-friendly approaches that should be very friendly to external contributors. Note that this is not a GitBook site — I judged that the GitHub Pages approach makes more sense for this site, which is more of a multifunctional hub rather than a single reference document.
I further tried to roughly straighten out all of our GitBook docs, including making sure that the list of docs is as complete as possible. In particular, I activated the WebGL SDK reference document and seriously overhauled it to match GitBook’s new scheme, with the following result:
https://worldwidetelescope.gitbook.io/webgl-engine-reference/
I’ve done a first pass of tidying things up and writing some new introductory material. I think this will be a very important document, since I think a key constituency in the WWT userbase can and should be people who make their own custom web interactives using the WWT WebGL engine. The source code to this document is in the worldwide-telescope-webgl-sdk-reference repository on GitHub.
When considering the code examples for that document, I realized that we had an issue because both of our site-hosting options — GitBook and GitHub Pages — force HTTPS by default, and if we want to show examples live in the browser we need to use insecure HTTP because of the well-known limitation that the main WWT website doesn’t support SSL. (Yet.) To work around this, I had to split the examples into their own repository and host it on a separate domain. (GitHub Pages allows you to use plain HTTP if you set up your docs to live on a domain other than github.io.) So, here is our newly refreshed list of WebGL examples, cross-linked to source code and viewable live:
This is another GitHub Pages site, living in the repository wwt-web-examples.
Finally, the documentation of how to write GitBook content isn’t so great anymore, I think because GitBook is trying to channel people into a proprietary workflow. So I wrote up what I figured out about how to set things up to work nicely in the GitBook framework. That document is here:
https://worldwidetelescope.gitbook.io/miscellaneous/documents/gitbook-spec
And its source code is in the wwtdoc-misc repository.
That’s a lot, but here’s the summary I want to emphasize:
If a person is interested in documentation or other things to enable contributions to WWT, their first stop should be the WWT Contributor Hub. If they can’t find the needed information quickly, that’s a bug that we should fix. Such bugs should be filed against the WorldWideTelescope/worldwidetelescope.github.io repository.