Page MenuHomePhabricator

Update app documentation to reflect new enhancements
Closed, ResolvedPublic

Description

Documentation needed:

  1. Javadocs for devs (inside code). Mainly to explain the new classes and methods created.
  2. Summary on GitHub wiki explaining what gets suggested and why.
  3. Modify https://www.mediawiki.org/wiki/Wikimedia_Apps/Commons ? Suggested by Niharika at T126848

Event Timeline

josephine_l updated the task description. (Show Details)
josephine_l raised the priority of this task from to Normal.
josephine_l claimed this task.
josephine_l moved this task from Backlog to Week-size tasks on the Commons-App-Android-Upload board.
josephine_l added a comment.EditedFeb 13 2016, 6:54 AM

I think we will be wanting documentation for both users and contributors? I figure user documentation is fairly straightforward, maybe I could see what I can add to the Google Play page. Contributor documentation will be a bit more tricky, as the preexisting codebase has very minimal documentation and I'm not familiar with many of the files that weren't part of my project. Maybe I could write a summary on the GitHub wiki for the files that I did create/modify? @Nicolas_Raoul and @Niedzielski , what do you guys think?

@josephine_l, sorry to be so tardy following up on this. I recommend at least documenting the new classes you added and methods where it make sense. In other words, don't document for documentation's sake. Document where it's useful.

Writing dev documentation for developers would be great, I guess it could be either a .md file in the app source code, or a page in Github wiki.
It would describe the rationale of the categorization suggestion strategy, and the API calls with sample request/response for each API used.

josephine_l updated the task description. (Show Details)Feb 16 2016, 3:21 AM
josephine_l set Security to None.

@Nicolas_Raoul @Niedzielski Javadocs have been added in the latest pull request. Currently still working on GitHub documentation to explain category suggestions - https://github.com/nicolas-raoul/apps-android-commons/wiki/Category-suggestions-(readme) .

On that wiki page, I see the following:

"before it was like this, now it is like that"

I think that what existed before is negligible anyway, so better simply write:

"it is like that"

That way, this documentation will be understandable by anyone. Cheers!

Thanks for the feedback @Nicolas_Raoul ! I changed the rationale for #1, but still not sure how to explain what we did for #3 without referring to prefix search. Will think on it...

josephine_l updated the task description. (Show Details)Feb 22 2016, 12:48 PM
josephine_l added a comment.EditedFeb 23 2016, 5:14 AM

Modified https://www.mediawiki.org/wiki/Wikimedia_Apps/Commons . @Nicolas_Raoul do you know which the most current repo for the iOS app is so we can link to them also? The repo on that page hasn't been updated for 3 yrs.

You can let #3 as is indeed.

The up-to-date links for iOS are at https://commons.wikimedia.org/wiki/Commons:Mobile_app

By the way, that page could use a few updates too :-)

@Nicolas_Raoul ah okay, thanks. Hrmm so I should update both https://www.mediawiki.org/wiki/Wikimedia_Apps/Commons and https://commons.wikimedia.org/wiki/Commons:Mobile_app ? Doesn't it seem a bit redundant to have so many pages about the same apps? Would be harder for future contributors to update also.

I think they serve different purposes, the mediawiki.org page being about the development project, while the commons page is a user guide. Much of the information would need to be moved around indeed: Removing "user guide" stuff from the first one, which is out of date anyway. The Commons page can keep a short history paragraph, but most of it should go to mediawiki.org I guess. Also, each one should link to the other.

@Nicolas_Raoul thanks, that clears things up a lot. :) Which 'user guide' stuff do you mean? I have been modifying the first one over the past few hours and I think I've taken out most of the irrelevant stuff, but I might have missed something?

I'll update the second one a bit and add the links.

Mostly the features list. The "Reports" paragraph can be removed too, I guess, we are not fond of user spying.

@Nicolas_Raoul Sorry, not too clear about this - do you think we should remove the entirety of the features list? I have pared it down quite substantially already.

It should be moved to the Commons page, and merged into the similar list that exists there already.
Maybe leave a link "For the list of features, see here"

josephine_l closed this task as Resolved.Feb 25 2016, 7:24 AM