Documentation: Consolidate Technical Documentation

[allella]

Quincy suggested all technical docs go into CONTRIBUTING.md on the Jan 25 2020 meeting.

• 1. Move https://github.com/freeCodeCamp/chapter/tree/master/server/docs to CONTRIBUTING.md
• 2. (edited) Move https://github.com/freeCodeCamp/chapter/blob/master/docs/how-to-open-a-pull-request.md into an collapsed / expandable section within Step 4 of the CONTRIBUTING.md
• 3. We can delete /docs/ directories, except /images since it's only general stubbed out stuff from really early on.
• 4. Is there a better place to store CONTRIBUTING.md screenshots than in /docs/images? If not, then do we want to rename it.
• 5. As with the "Step 4" note above, we can / should use expandable sections in CONTRIBUTING.md to make certain sections not take up as much space until someone clicks to expand.
• 6. @Narutuffy was looking to get involved and I thought it could be an easy first contribution
• 7. Improvements to CONTRIBUTING.md on the technical side. - Closed via Update DOCS #396 and Improve Node, Docker, Postegres and Other Sections of CONTRIBUTING.md #447
• 8. This also begs the question of if some of the README.md technical documentation is better in CONTRIBUTING.md. These sections of the README may be better in CONTRIBUTING.md: Schema, API Specs, Testing - Closed via Move server/docs/README.md into CONTRIBUTING.md, per Quincy #397

[allella]

The /docs/images and /docs/how-to-open-a-pull-request.md are used or linked to from within the CONTRIBUTING.md, so we don't want to delete them without consolidating.

[allella]

8. This also begs the question of if some of the README.md technical documentation is better in CONTRIBUTING.md.

These sections of the README may be better in CONTRIBUTING.md

• Schema
• API Specs
• Testing

@Zeko369 @timmyichen would you agree on moving these sections and/or any others?

[Zeko369]

@allella Thank for openinig this PR and bringing this up. And sorry for the late replay I had a lot of stuff to do yesturday.

1. I was working on something but don't have a PR open, I'll do it with @Narutuffy.
2. Agreed, but we should also add how to pull other peoples branches, and maybe how to push to them (this can only be done by people with maintainter or higher level access to this repo, but seems important non the less)
3. Agreed
4. I'd keep it in docs/images or maybe rename it to docs/assets
5. Yes, that would be quite neat
6. I think that @Narutuffy should rewrite parts of the docs, or at least just do this migration
7. I think that @Narutuffy should rewrite parts of the docs, or at least just do this migration
8. We should move that to the CONTRIBUTING.md, but there are some things about them that need to be changed, for example the Schema image generation Schema image / ER Diagram is out of date #54, API (swagger.json) docs need to be heavily refactored.

[allella]

Regarding 4, how about we create an
/assets
directory and move everything out of the /docs directory?

@Zeko369 I assume there will be other assets for the front end. Is there a pattern from another project we'd like to use to store web app assets, including the limited number of docs images?

[Zeko369]

@allella For the next.js all the assets are in the /public folder, and I don't really think we should put docs images there, I'd keep it in docs/assets so we can differentiate them from the app assets.

[allella]

Alright, @Narutuffy, are you still available to help with this issue? Many of the steps are mentioned above, but I can assist and confirm.

[Narutuffy]

Yeah definitely, I will ping you and confirm for overall clarity @allella I'll start working on a branch.

[allella]

@Narutuffy I've updated this issue with a checklist and you knocked out 2-6. If you can help with 1,7,8, then I suspect these tasks and conversations should lead to other ways you can contribute on the more technical aspects.

8. is related to Schema image / ER Diagram is out of date #54 because the issue was re-opened to talk about automatically generating a schema E-R Diagram image so the documentation is always updated when the schema changes. @Zeko369 worked with I just commented that it looks like Github Pages would allow us to host the /docs directory, which could potentially allow us to host the interactive SchemaSpy files at a URL like https://freecodecamp.github.io/chapter/schema

[allella]

@Narutuffy this is simple, but the following images can be deleted. They were part of an issue and I moved the screenshots into that issue.

• docs/assets/GoogleGeneratedSnippet.png
• docs/assets/MeetupGroupEventSERBreadcrumbs.png
• docs/assets/RegularSER.png

[allella]

@Zeko369 @nik-john I seem to recall the Swagger documentation was hosted on a custom HTTP port, like http://localhost:8000/api/v1/docs

I don't know if this is a good idea, or even possible, but could we export Swagger HTML files to /docs/api automatically so they can be viewed through the GitHub pages? Or, is it best to leave it as-is and expect developers to visit the custom HTTP port to see those docs?

[allella]

@Narutuffy @Zeko369 for task 8) on this issue, I think as a first step we should consolidate all the remaining sections we want into CONTRIBUTING.md and then talk about refactoring them.

I think if we wait until everything has been refactored, then we'll delay and complicate an otherwise easy copy / paste and reformat.

Does everyone agree to move the following sections into CONTRIBUTING.md in their current state? Or, would we like to keep any of the README.md sections below in the README?

• Development Setup
• server/docs/README.md
• Testing
• API Specification
• Schema

[allella]

@Narutuffy I hope things are safe and stable in your life and community.

I'm going to have time to contribute more on the documentation. I can continue with the remaining steps, but if you have time to continue, then please let me know to avoid duplicating efforts.

Thanks

[allella]

I'm going to continue this issue and consolidate the existing technical documents (1 and 8 above) into CONTRIBUTING.md and we can continue updating the Docker section and others once it's all in one place.

Quincy shared the freeCodeCamp contributing domain / page as an example of having things in one place. This is a first step in that direction.

[allella]

#1 from the list above is targeted by #397