Organize existing project-wide documentation into this central repository

[kytrinyx]

This is the documentation that we have. We need to:

• decide how to organize the documentation
• copy documentation into the new locations
• update documentation links throughout the project
• delete documentation from old locations

exercism/exercism.io

This is in the docs/ directory (https://github.com/exercism/exercism.io/tree/master/docs)

docs/
├── filing-a-bug-report.md
├── fixing-exercise-readmes.md
├── flipper-feature-flags.md
├── getting-involved-in-a-track.md
├── img/*
├── improving-consistency-across-tracks.md
├── inviting-new-maintainers.md
├── maintaining-a-track.md
├── overview-architecture.md
├── overview-of-exercism.md
├── porting-an-exercise.md
├── reviewing-a-pull-request.md
├── roadmap.md
├── setting-up-local-development.md
├── the-contribution-workflow.md
├── the-exercism-way.md
├── triaging-issues-in-a-track.md
└── writing-track-documentation.md

We also have a CONTRIBUTING file in exercism/exercism.io which has a lot of project-wide content.

exercism/x-common

This is the table of contents of the CONTRIBUTING file (https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md).

• We Will Gladly Help You Help Us
• Code of Conduct
• Overview
• Updating an Exercise Test Suite
  • Updating a Generated Test Suite
• Tweaking a README
• Porting an Exercise to Another Language Track
  • Providing Feedback on the Site for an Exercise You Implemented
• Implementing a Completely New Exercise
• Improving Consistency By Extracting Shared Test Data
• Writing a New Test Suite Generator
• Track Anatomy
• Starting a New Track
  • Beta-Testing a Language Track
• Maintaining a Track
• Useful Tidbits
  • Pull Request Guidelines
  • Exercise Versioning
  • Anatomy of an Exercise
  • config.json
  • Track-Level Linting With Configlet
  • Git Basics
    • Getting the Code
  • Branches
  • Commit Messages
    • Resetting master
    • Squashing
    • Resources

[kytrinyx]

Here are some of the categories that I see (not exhaustive).

• welcome / high level orientation
• roadmap
• general best practices
• contributing to language tracks
• contributing to the website/product
• maintaining language tracks
• setting up a local development environment
  • website-specific (should remain in exercism/exercism.io)
  • entire ecosystem (website, api, CLI, configured to work together locally)
• task-oriented guides (e.g. "update an exercise README", or "port an exercise")

[ErikSchierboom]

I love the proposed categories, and especially the task-oriented guides.

[kytrinyx]

OK, cool. It sounds like that might be good enough to get started, then.

[kytrinyx]

I think that the basic structure should be something like this:

• a top-level README that provides a map to the entire repository. People should be able to quickly orient themselves from the README and get directly to the documentation that they need. It should not be a wall of text. We'll probably want to add that last, since until we have the rest of the structure, it's hard to say what all goes in it.
• directories for each category. Each directory should have a README, which contains the high-level documentation for the category, and then separate files for different topics within the category.

[kytrinyx]

I've added a couple of pull requests, and the guides have ended up in a directory with related documentation so far. I'm not sure we'll end up with a separate directory for guides.

[kytrinyx]

The entire top section of the exercism/exercism.io CONTRIBUTING.md document is a decision tree that @jtigger developed for figuring out where to go next.

I'd like to suggest that we put this in separate files like this:

.
├── i-have-an-idea
│   ├── README.md
│   ├── a-brand-new-exercise-for-exercism.md
│   ├── improving-an-existing-exercise.md
│   ├── improving-the-command-line-client.md
│   └── making-the-website-better.md
├── i-see-a-problem
│   ├── README.md
│   ├── getting-started-with-a-language.md
│   ├── on-the-website.md
│   ├── with-a-specific-exercise.md
│   └── with-the-command-line-client.md
└── i-would-like-to-help
    ├── by-mentoring-others.md
    ├── in-go.md
    ├── in-ruby.md
    ├── with-a-particular-language.md
    ├── with-technical-writing.md
    ├── with-web-design.md
    └── with-web-programming.md

[parkerl]

@kytrinyx what's your aim in breaking that document apart? Is it so that the end user sees less of a wall of text? Or is it to make maintaining the docs easier? I have concerns about making the docs too fine grained.

[kytrinyx]

@parkerl I find it a bit overwhelming to have a long document like that, and navigating between sections is confusing to me, because when you link to a (short) section, you also see the sections after it.

I've pushed up a suggestion in #5

[kytrinyx]

@parkerl How about breaking it into three files instead of all the way down into granular files?

[kytrinyx]

@parkerl I've decided to do a direct copy for now (though I'm experimenting with icons). We can discuss later whether or not it's useful to break the document apart a bit.

[parkerl]

Ok. Sounds good.

On Mar 19, 2017, at 12:22 PM, Katrina Owen notifications@github.com wrote:

@parkerl I've decided to do a direct copy for now (though I'm experimenting with icons). We can discuss later whether or not it's useful to break the document apart a bit.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[ErikSchierboom]

I find it a bit overwhelming to have a long document like that, and navigating between sections is confusing to me, because when you link to a (short) section, you also see the sections after it.

I have the exact same feeling. Having one page with lots of contents is not the best way to display contents on the web I feel, it's why we have hyperlinks after all, to link to other pages. But just doing a direct copy and having a discussion later seems wise.

[jtigger]

Organizing this stuff is not easy.

I see an overlap with advice around designing microservices:

1. keep everything together and learn your Bounded Contexts.
2. As you truly understand each context and see the grains, break them out.

The Bounded Contexts in Exercism I see (with potential sections)... I'm sketching to express the idea:

• Deliberate Practice — A practitioner using Exercism.
  • Getting Started
  • Giving and getting advice
  • Teams
  • Being a language mentor
  • "Games" you can play on Exercism (e.g. categorizing, trade-offs, exercise extensions, ...)
• Tweekfixing (?) — A practitioner making a light-weight contribution.
• Contributing — An Open Source contributor submitting a non-trivial PR.
  • Design of Exercism
  • ...
• Maintaining a Track — A member of the Exercism organization tending to a language track.
  • Goals & Roadmap
  • ...
• Maintaining the Product — A member of Exercism organization tending to a software component.
• Marketing — Educating others on the value of Exercism.

...

[kytrinyx]

@jtigger that makes sense. Let's get everything in here and see what we have, and then discuss improvements to it.

[jtigger]

I'm feeling a little dense, @kytrinyx. I want to help out but I'm not sure where we're at.

• I see some files .md files are here, some are not.
• There's a start to a discussion about organization, but we can't get too far without having the pieces on the table.

Are we at the point of mechanically pulling files over into this repo from the various sources, listed above?

[kytrinyx]

Sorry @jtigger that is totally my fault.

Are we at the point of mechanically pulling files over into this repo from the various sources, listed above?

Yes!

I jumped the gun starting to talk about where things go. I think if we even just get everything in here, we can get a better view of what's here, what's not, and how to organize it.

[kytrinyx]

I think we now have open issues or PRs for everything. I'm going to go ahead and close this, and we can open new issues/PRs as we discover missing or confusing (or left-over) documentation.