How does one submit a tutorial to this repo?

[jlaura]

Description

We currently have zero documentation on how to submit a tutorial to the repository, so asking users to submit tutorials is a bit 'problematic'...

Suggested Edit

Add a wiki page on how to submit tutorials...

Thanks!

[jessemapel]

The current plan is to house these in our wiki. Unfortunately, you cannot submit a pull request to the wiki repository. This means contributors would have to directly push to the wiki repository. This is both unsafe and also limits contributors to only those with write access to the whole repository. As, we expect our users to help with these, limiting the contributors is particularly problematic. There are a couple possible solutions:

1. Move the contents of the wiki into the main repo. This will allow people to create pull requests and contribute to our documentation. We already have our website documentation, or at least what is used to make it, in the repository. If we are okay with having user documentation in the repo along-side the code then this is a simple solution. On the other hand, this makes our repo even bigger than it already is. It can also be confusing for users to go to the source tree to find documentation.

2. Create a separate repo for the wiki. We can clone the existing wiki repo and push it into a separate github repository. This would allow for users to contribute to the wiki documentation and track issues separately. If we want to keep the documentation separate from the source code, this would be a good path. This would create a second repo that we have to manage permissions and keep up to date on. It also, makes it a little harder for users, we would probably end up with documentation issues being posted on the main repo, the docs repo, and astrodiscuss.

3. We can have contributors submit a patch that then gets verified and applied by someone with write permissions. Users can create their own github/local repo that is a clone of the wiki repo. Then, they can make changes and submit a patch for us to apply to the wiki. This keeps the docs associated with the main repo. It also, allows people without write access to contribute. This process is not particularly elegant though and requires a bit of knowledge on the contributor's part. it also creates more work for maintainers who have to hand verify and apply the patch. Finally, without a formal pull request, it's hard to iteratively update things, we'd have to use e-mail or issues to facilitate discussions.

I'm not sure which option is best, I would recommend the first or second. Any comments would be great.

[jlaura]

I would vote for #2. I think I would be nice to have our docs in a separate repo at some point. I realize this is challenging because some of the docs are built from source. On the point about issues being posted to the main repo, we have two options: (1) we can manually migrate as we do not get a high volume of documentation issues or (2) we can get a bot to auto-migrate documentation issues to the new repo (this is quite easy).

I also remember recently seeing that git now supports cross repo symlinks, so we might even be able to symlink the wiki docs from one repo into the other. Not something to worry at all about now.

My larger concern is getting this open so #1 or #2 both, as indicated, achieve that goal. #2 is my preference for separation of concerns and openness.

[rbeyer]

This is about 'tutorials' (which are a flavor of documentation) or this is about all the documentation for ISIS?

[jlaura]

The original post is about the wiki contents and tutorials. What is the best mechanism to accept PRs on those so that the community can also contribute back.

The discussion morphed a little into the source information that is used in rendering and populating all documentation.

[rbeyer]

That's what I was afraid of, so I'm glad I asked.

If you're talking about tutorials only then a separate repo might be tractable. Odds are good its going to have a lot of images and possibly videos. I don't need to enumerate how that's difficult for any repo. You maybe need to think about exactly what kind of 'tutorial' you're trying to collect (a text and still images tutorial is fundamentally different than one that is supplemented by video or entirely video). But if we're just talking about tutorials that read like a magazine article (they include text and figures), I'd keep them with the source. They are inherently tied to particular spans of versions of the software, itself, and putting them in a separate repo means you'd have to do a lot of version dependency tracking with your tutorials which is an extra step. There are drawbacks to both approaches, but it is not clear that a separate repo solves more problems than in generates.

If you are talking about all documentation then a separate repo is a terrible idea. Don't do that. You'll spend all your time cross-linking to keep things current, spending effort to make sure your document repo is correctly tracking your code repo (:shiver emoji:), when you could just keep it in the same repo and not have that problem.

[jessemapel]

@rbeyer I agree keeping the API and application docs with the source code makes sense. I think higher level documentation about how to string applications together and the website make sense in a separate repo.

[jessemapel]

For right now, I have cloned the wiki on a separate repository:

https://github.com/USGS-Astrogeology/ISIS_wiki/tree/master/tutorials

Tutorials can be submitted via pull request on that repo. In the future I want to investigate how to setup automated merging and pushing to the wiki on this repo.