Documentation work items

[ghost]

This issue is here to track the progress of updating, trimming down, and adding to the current Zen Audio Player docs & wiki pages. The four files/sections for docs are as follows: CONTRIBUTING.md, ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md, and the Wiki pages. The main tasks that we are prospectively looking to address are:

• [ ] Decide what amount of content to move from markdown files (Contributing, Issues, PRs), to Wiki pages (I think the issue & PR templates are too verbose, we should have a simpler checklist for both, ideally under 5 items)
• [ ] How to test things locally (WAMP, MAMP, XAMPP) vs. opening the index.html file in a browser (we should recomment just running npm install then npm start for "running" the site, then npm test to run the tests - the main requirement here is Node.js 4.0+)
• [ ] How to write tests & run tests
• [ ] What are our code conventions/style? (a .jshintrc would help a bunch here) (see .eslintrc.json, coordinate those rules with the eslint docs and we could make something more human readable on the wiki)
• [ ] How to install dependencies (frontend & test) (npm install for "running" and testing, bower (frontend) depdendencies are checked in, but in order to update I believe you run bower update --save <package-name>)
• [ ] What to look for in a successful/unsuccessful work session (nothing specific here, but the goal is always to minimize the diff, ie: don't go refactoring unless it's necessary because the diff becomes difficult to review)
• [ ] Tools (why did we pick certain things? bower/node.js/specific dependencies/gitter/travis CI) - (there are some notes in @shakeelmohamed's blog post ping him for any additional info)
• [x] What is the contributing process like? (@shakeelmohamed's code review on the PR, contributor updates PR, repeat until everyone is satisfied)
• [x] How to get started quickly as a newbie
• [x] Branching model (basically master is locked down, and can only be pushed to via a PR that passes code review)

[ghost]

Hey @shakeelmohamed, let me know if you'd like to revise anything here. I based this off the original list in the other issue. Perhaps we can also close issue #49 once this one looks good to go.

[shakeelmohamed]

I've left some comments bold inline above to help whoever ends up doing these tasks, thanks for triaging @josectello!

[ghost]

@shakeelmohamed Are we thinking of adding any future content (from the list) to only the Wiki pages or do you think any of these items will require PR's - or the creation of another markdown file?

[shakeelmohamed]

@josectello aside from the first item on the list, I think the others make sense being on the wiki. What do you think?

[ghost]

@shakeelmohamed I like the idea of having denser content in the Wiki, but I often find myself (when looking through open source repos) completely forgetting that a Wiki tab even exists.

What about inserting a link someplace on the main README.md to the Wiki?

[shakeelmohamed]

@josectello that makes sense, we can add a link to the wiki at the end of the contributing section of the README 👍

[FleetAdmiral]

Is the discussion still on for this?

[shakeelmohamed]

@FleetAdmiral Definitely, I'd like to see these items done one at a time FYI

[FleetAdmiral]

@shakeelmohamed Cool with me, can i pick any item too look into or is there an order you'd like to follow?

[shakeelmohamed]

@FleetAdmiral you can start with any of them

[erikasf]

Hi, Is this still a need? If so I would like to help out on this issue. I"m a first time open source contributor if thats okay with you all, having a newb mucking things up?

[shakeelmohamed]

@erikasf Yes please! Ping me if you have any questions

[brechtdedecker]

Hello, I'm a first time open source contributor as well, please could you tell me what still has to be done of the documentation ? Thx in regard

[shakeelmohamed]

Welcome @brechtdedecker! Please see the original post on this issue for the checklist of uncompleted items

[ghost]

Hi, I'm a somewhat experienced contributor. I'm working on the third item on the list.

[shakeelmohamed]

@Kelby-Baca thanks! I've re-ordered the list so completed tasks are at the bottom. That task is now first on the list

[fchikwekwe]

Hi there! I'm a first time contributor. I would like to help you with the first issue on your list involving the issue and PR templates. Did you just want them to be more succinct?

[shakeelmohamed]

@fchikwekwe yeah, they're just too verbose and aren't providing much value. Go ahead and make a PR, we can discuss once you've started

[fchikwekwe]

@shakeelmohamed I submitted a PR with some suggestions for changes. Feel free to look over it and let me know which direction you'd like for me to go.

[ayush220]

I have started working on this issue

[adetyaz]

Hey everyone, first time contributor here. How can I start and what needs to be done.

[shakeelmohamed]

@adetyaz hello and welcome! Take a look the checklist at the top of this thread, let me know if you need clarification on any of those tasks

You can take a look through the wiki to see what we've got so far

[adetyaz]

Thanks @shakeelmohamed , I'll dive into that and let you know when I need any help.

[SoundaryaKoutharapu]

Hi @shakeelmohamed Can I work on pull request template.? I guess, They ain't one.

[shakeelmohamed]

@SoundaryaKoutharapu we actually do have one, but it’s quite verbose. I don’t even use it myself. Feel free to submit a PR with some changes: https://github.com/zen-audio-player/zen-audio-player.github.io/blob/e3694e97ee74aa6f0a8c6b5c6703d9a02b355d58/.github/PULL_REQUEST_TEMPLATE.md

[SoundaryaKoutharapu]

Hi @shakeelmohamed Can you confirm whether this template meet your requirements? Suggest me if any changes required.

Pull Request

Description

[Provide a brief summary of the purpose and context of this pull request. Why are you making these changes?]

Changes Made

[Explain the changes you've made in detail. List new features, bug fixes, or improvements, and include links to related issues if applicable.]

Screenshots (if applicable)

[Include screenshots or GIFs to visually demonstrate the changes, if relevant.]

Checklist

• [ ] I have read and followed the project's contributing guidelines.
• [ ] I have tested the code to the best of my ability.
• [ ] My code follows the project's coding style.
• [ ] I have made necessary updates to the documentation.

Related Issues

[Reference any related issues or pull requests by linking them here.]

Additional Notes

[Include any additional information or context that might be helpful for the reviewer.]

[shakeelmohamed]

Hi @SoundaryaKoutharapu, I would like to trim most of this content. We can start a more involved discussion in a pull request.

Description, changes made, and additional notes can be simplified into one description section at the top. The checklist can be trimmed to the first and last points.

Let’s start there and see how it looks.

[SoundaryaKoutharapu]

Hi @shakeelmohamed, I've made the changes, can you please review it?

Pull Request

Description

[Provide a brief summary of the purpose and context of this pull request. Why are you making these changes and Explain the changes you've made in detail]

Screenshots (if applicable)

[Include screenshots or GIFs to visually demonstrate the changes, if relevant.]

Related Issues

[Reference any related issues or pull requests by linking them here.]

Checklist

• [ ] I have read and followed the project's contributing guidelines.
• [ ] I have made necessary updates to the documentation.

[shakeelmohamed]

@SoundaryaKoutharapu Looking good, let’s check capitalization, punctuation, spelling, etc. Please open a pull request with these changes.

[SoundaryaKoutharapu]

sure @shakeelmohamed