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.mdisn't linked-to from the rootREADME.md. However, rather than linking to it, we might just want to get rid of the file, and mention Chrome Remote Debugging inREADME.md--sinceREADME.mdalready contains much of the information inandroid.mdin a more compact form (as it links out to more well-maintained external documentation).- The file
_docs/get_started/README.mdseems to duplicate a lot of the information contained in the rootREADME.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_docsdirectory entirely.- It seems like
SUMMARY.mdis 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.jsfile 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