Openj9: To Wiki or not to Wiki?

[JamesKingdon]

Would it be worthwhile to use the Wiki page on this project to gather some basic documentation? Perhaps covering slightly more technical issues than https://www.eclipse.org/openj9/oj9_faq.html and with links to where to find further detail.

[DanHeidinga]

There's also the /docs folder where we could store some of that kind of content.

Someone (@rwy0717 ?) suggested that keeping the data in the repo is better than putting it in the wiki so anyone who clones it will have a copy and we won't lose data in the very very unlikely event the project migrated to another hosting service.

[JamesKingdon]

It's a valid point, but we forgo a lot of ease of use and accessibility with the /docs approach. I would be concerned if there was no way of migrating wiki based content if the need arose though.

[rwy0717]

Checking notes into /docs has advantages (offline access, etc), but I'm doing it in a project where it's very easy (for me) to commit. I can see how getting docs into openj9 might be too much friction--especially for informal notes; or it could bog down committers with too many PRs. The wiki could be a lot easier.

[JamesKingdon]

I did a quick test on one of my forks, and the wiki is easily extracted with git clone, arriving as a collection of .md files (with full git history). Seems very workable. I haven't explored what access control is available on the wiki pages.

[DanHeidinga]

We discussed this on today's community call and generally agreed that the following things need to be figured out before we would create a wiki. Some technical concerns and others more organizational.

• [ ] Access controls - who can make changes to the wiki. Just committers or everyone?
• [ ] What kind of info belongs on the wiki?

The second one is larger concern about how do we group information so that everyone knows where to find it and where to create similar information. The project already has:

• a website with its own repo
• a set of docs with its own repo
• the /docs folder in this repo
• the OMR project for OMR-related information
• issues
• slack
• mailing lists

All of which are used (or not) in different ways by committers, users, etc. There needs to be a clear purpose to info on the wiki so anyone would know which is the right location to look at.

[JamesKingdon]

It sounds like the primary purpose of the wiki might be to act as a jumping off point to all the other places where documentation exists.
Issues/slack/mailing lists are I think a different category of thing, potentially useful to those that need to do project archaeology, but not a first choice of where to find documentation. OMR will necessarily do their own thing. That leaves us with the first three in your list and the question of whether the wiki can usefully supplement them.

[SueChaplain]

A clear content strategy will help us decide where content should live and help contributors find it. As @DanHeidinga points out, we already have a number of repos and places where things might live and I've heard comments from people that certain things can be "hard to find". @JamesKingdon you started this discussion for doc that was more in-depth than the FAQ. Not sure what type of content you are referring to, but maybe it slots in somewhere below.

Pulling together a list, we have our starting point, and then 2 main groups:

1. Content a user needs to know to build or use an OpenJDK with OpenJ9.
2. Content a contributor needs to know to work with the project.

Starting point - High level project info
We have the website, which is intended as our shop window. The place that connects both users and contributors with key project resources, including our Eclipse project page, Slack channel, mailing list etc.

1. User content

How to use an OpenJDK with OpenJ9 - the user documentation:
We are nearly there with the first contribution - the "command ref", which will be hosted at the OpenJ9 website (but built from a different repo eclipse/openj9-docs). Once this is established we'll grow it to cover all the areas we have in the old IBM SDK documentation (perf tuning, troubleshooting etc).

How to programatically use OpenJ9 extensions - the API documentation:
Don't think this is being built at the moment. Believe @pshipton has a plan here but nor sure where the built doc will reside? I would suggest either the website or the openj9 repo in an obvious folder.

How to build an OpenJDK with OpenJ9 - our detailed build instructions:
Our detailed build instructions per platform are currently in the openj9/buildenv directory with build artifacts like Docker, but could be relocated elsewhere to avoid fragmentation.

Release notes:
To support notable changes for each OpenJ9 release, linked to from the GitHub release page. Currently in openj9/docs/release-notes.

2. Contributor content

Technical developer documentation:
Detailed developer doc that will help contributors understand the guts of OpenJ9 components so that they can contribute. I think this doc has started to form in the eclipse/doc directory, but is partially complete and has no real "index" of content. Using something like MkDocs for this content (as we have done with the user doc) would allow it to be built and hosted as HTML with a proper index. If it remains where it is, I think an index should be created in the /doc ROOT so that people can find what they are looking for and know what is missing. Links to doc at OMR included here too.

Process documentation:
Information that we need to share for working processes. We have the release process and GitHub labelling strategy in eclipse/doc, but there are probably other processes that could be written up. (The website has some too with specific place to go). Sensitive content, including passwords, needs protecting, but, IMO, everything else could go into a GitHub wiki.

Where do we keep that sensitive content? It should be somewhere safe that all committers have access to. Does Eclipse have anywhere for this type of content?

And finally.... users or contributors, depending on what is covered......

Blogs:
Not to omit the recent discussions around a site to host blogs, which should conclude shortly. The wordpress vs jekyll debate. Where ever this ends up, we'll need to link to it from the OpenJ9 website.

Hopefully all this waffle helps us close on a placement strategy.

[JamesKingdon]

Thanks Sue, that helps lay out the land really nicely. My original thought for the wiki would have fitted in as part of the area you describe as "Technical developer documentation". It was triggered by reading a really useful comment in one of the issues and thinking that we need a way of capturing such info. Generally these are smaller pieces of text than fit naturally in the docs directory (often just a para or two), but would be easy to capture in the wiki format, as either an entry on a larger page or linked page of it's own. Part of the idea is that it should be easy to add information to the wiki - we want to make it easy to capture useful information.

This discussion has frequently noted that we have a lot of different places where information is held. Because the wiki is a feature of every github project there is an expectation that it's where you go to get started with a project's documentation. If we did nothing else, using the wiki as an index into our other documentation sources would be worthwhile.

[SueChaplain]

Ah OK, I see the type of content you are intending and why a wiki would be easier to update. Keeping it under control is another consideration though as this type of thing can grow quickly and has a tendency to get stale.

[SueChaplain]

Regarding access control for wikis (from GitHub help):

Changing access permissions for wikis
Only repository collaborators can edit a public repository's wiki by default, but you can give anyone with a GitHub account edit permissions.

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click "Settings".

3. Under Features, unselect "Restrict edits to collaborators only".

[DanHeidinga]

collaborators == committers? We don't have direct access to the settings for the wiki - only the Eclipse Foundation does. The webmaster will action most reasonable requests we make.

[JamesKingdon]

No, it seems collaborators is a finer grained acl to which you can invite individual users: https://help.github.com/articles/inviting-collaborators-to-a-personal-repository/

[SueChaplain]

Isn't that process for personal repos rather than those that are owned by an organisation?

[JamesKingdon]

Ah, could be. Perhaps I should have read further.

[JamesKingdon]

I'm skimming, bit editing wiki appears as row in the table on this link: https://help.github.com/articles/repository-permission-levels-for-an-organization/

[dsouzai]

Is this still something that's worth discussion or should we close this issue?

[DanHeidinga]

Given it's been dormant for so long, closing