Closed kytrinyx closed 7 years ago
Here are some of the categories that I see (not exhaustive).
I love the proposed categories, and especially the task-oriented guides.
OK, cool. It sounds like that might be good enough to get started, then.
I think that the basic structure should be something like this:
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.
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
@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.
@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
@parkerl How about breaking it into three files instead of all the way down into granular files?
@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.
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.
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.
Organizing this stuff is not easy.
I see an overlap with advice around designing microservices:
The Bounded Contexts in Exercism I see (with potential sections)... I'm sketching to express the idea:
...
@jtigger that makes sense. Let's get everything in here and see what we have, and then discuss improvements to it.
I'm feeling a little dense, @kytrinyx. I want to help out but I'm not sure where we're at.
Are we at the point of mechanically pulling files over into this repo from the various sources, listed above?
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.
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.
This is the documentation that we have. We need to:
exercism/exercism.io
This is in the
docs/
directory (https://github.com/exercism/exercism.io/tree/master/docs)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).
master