mozilla/webmaker-core

Remove duplicate and unmaintained docs

Open

#266 opened on Jul 14, 2015

View on GitHub
 (0 comments) (0 reactions) (0 assignees)JavaScript (31 forks)auto 404
documentationhelp wanted

Repository metrics

Stars
 (63 stars)
PR merge metrics
 (PR metrics pending)

Description

This issue has been migrated from mozilla/webmaker-android#2364.

It was originally written by toolness on Mon Jun 29 2015 and had the following description:

The following recommendations are based on the philosophy of maintaining as little documentation as possible in webmaker-android, because without a documentation lead and/or doctests, it's really easy for our docs to fall out-of-date and cause more confusion than help. Instead, I recommend linking-out to external, well-maintained documentation whenever possible, and relying on developers to connect the dots.

It's not exactly a red carpet, but it's better than a red carpet with spikes and trapdoors in it. :grin:

Anyways, even if you disagree with the philosophy, the following recommendations may still be useful:

  • The file _docs/android.md isn't linked-to from the root README.md. However, rather than linking to it, we might just want to get rid of the file, and mention Chrome Remote Debugging in README.md--since README.md already contains much of the information in android.md in a more compact form (as it links out to more well-maintained external documentation).
  • The file _docs/get_started/README.md seems to duplicate a lot of the information contained in the root README.md. I think we might want to simply get rid of it. If we do this along with the aforementioned suggestion, I think we can get rid of the _docs directory entirely.
  • It seems like SUMMARY.md is not very useful in a similar way, so we should probably get rid of it too?
  • It looks like all the aforementioned files were all initially added in https://github.com/mozilla/webmaker-android/commit/4537c9b1edcbdbbe2375ff55599bcdc181d4e19b, which looks like it also added a book.js file in the root directory. It mentions gitbook... Until we're ready to fully commit to maintaining gitbook-based documentation, I guess I recommend getting rid of this file too. There may also be other build steps related to gitbook in the code that we might want to get rid of too.

On Mon Jun 29 2015, thisandagain commented:

:+1:

On Mon Jun 29 2015, toolness commented:

Rad! I'm totally fine w/ contributing a PR to this myself, my only concern is whether there is additional gitbook-related code in the build system that I don't know about. Not sure if I should issue a PR now or wait for **@**k88hudson to get back from PTO, since she seems most familiar w/ this part of the code?

On Mon Jun 29 2015, thisandagain commented:

I think we can issue a PR now as long as we capture (or push to another resource) the Android setup info into the main README.md here: http://webmaker-mobile-guide.mofodev.net/_docs/get_started/android.html

Contributor guide