Page MenuHomePhabricator

[2 hours] Update QuickSurveys and RelatedArticles documentation
Closed, ResolvedPublic

Description

Some issues were brought up at T152036#2861383. Let's fix them. Pasting here too:

Some of these extensions could use a documentation refresh. The QuickSurvey docs on how to actually a survey are too vague to be useful (I ended up not testing it). RelatedArticles has some strange behavior which should probably be mentioned on the description page ($wgRelatedArticlesShowInFooter gets ignored if BetaFeatures are not installed; $wgRelatedArticlesUseCirrusSearch gets ignored in the sidebar); $wgRelatedArticlesShowReadMore does not seem to exist anymore.


AC

  • Both extensions have a "Getting Started" section in their documentation.
  • Both extensions' dependencies are documented.
    • Are the dependencies hard or soft?
  • The subtleties of the config variables mentioned above are documented on mw.org.
  • The process of creating and enabling a survey is documented on mw.org.
    • Are there any differences between dev and prod?

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptDec 21 2016, 11:09 PM
bmansurov updated the task description. (Show Details)Dec 21 2016, 11:11 PM
phuedx renamed this task from Update QuickSurveys and RelatedArticles documentation to [2 hours] Update QuickSurveys and RelatedArticles documentation .Dec 23 2016, 9:48 AM
phuedx triaged this task as Normal priority.
phuedx moved this task from To Triage to Triaged but Future on the Readers-Web-Backlog board.
phuedx added a subscriber: phuedx.

I've added a provisional estimate of 2 hours. Honestly, though, good documentation is hard to write so it might be worth bumping to 4.

phuedx updated the task description. (Show Details)Dec 23 2016, 9:52 AM
Restricted Application added a subscriber: TerraCodes. · View Herald TranscriptMar 20 2017, 8:15 PM
Jdlrobson added a subscriber: Jdlrobson.

@ovasileva if we are swatting a new QuickSurvey for analytics, now would be a perfect time to do this.

bmansurov moved this task from To Do to Doing on the Reading-Web-Sprint-96 board.

@phuedx reading your A/C I wonder if we should only document on mediawiki.org and add the link to README. That would help us avoid duplicating our work. What do you think?

@bmansurov sounds good to me. The wiki can be updated and translated so plus points!

Change 349258 had a related patch set uploaded (by Bmansurov):
[mediawiki/extensions/QuickSurveys@master] Add link to documentation

https://gerrit.wikimedia.org/r/349258

@bmansurov, @Jdlrobson: Yuuuuge 👍 for translation of the docs.

bmansurov moved this task from Doing to Needs Code Review on the Reading-Web-Sprint-96 board.EditedApr 20 2017, 5:40 PM

Please review the above patch and documentation of QuickSurveys while I work on RealtedArticles. Note that I didn't add a "Getting started" section as I haven't seen that done before and other extensions we maintain don't have that section. I kept it simple and added missing parts and removed old documentation.

Change 349258 merged by jenkins-bot:
[mediawiki/extensions/QuickSurveys@master] Add link to documentation

https://gerrit.wikimedia.org/r/349258

Jdlrobson reassigned this task from bmansurov to pmiazga.Apr 20 2017, 10:42 PM
Jdlrobson added a subscriber: pmiazga.

Looks good to me. I made a few edits of my own (@bmansurov please do check them!).
@pmiazga and @phuedx would you like to take a look and see what you think?

@Jdlrobson your changes look good.

pmiazga added a comment.EditedApr 25 2017, 12:51 AM

Documentation looks good, my only concern is that README files in both projects contain only a link to MediaWiki page. It would be helpful to put installation guide (it won't change) and some basic configuration information inside README file. How to install/configure an extension is a crucial information and it is a basic requirement for any project. For any other information, we can leave a link to public MediaWiki documentation.

Per above - Acceptance Criteria says

  • The subtleties of the config variables mentioned above are documented in the README and on mw.org.
  • The process of creating and enabling a survey is documented in the codebase and on mw.org.

As mentioned above codebase doesn't contain the description of config variables, nor how to install an extension - because of that I'm moving this task back to "Needs more work".
IMHO we can skip documenting the process of creating and enabling survey in codebase as this action is more likely to change in future.

@bmansurov @Jdlrobson - any thoughts?

pmiazga reassigned this task from pmiazga to bmansurov.Apr 25 2017, 12:51 AM
pmiazga moved this task from Ready for Signoff to Needs More Work on the Reading-Web-Sprint-96 board.

QuickSurveys

I've gotten rid of the old release info.

Looks good to me, seems like the existing docs were pretty good.

RelatedArticles

Looks good to me.

I'd like to see us kill Cards and fold it into RelatedArticles sooner than later. It is a failed experiment that has been going on for too long.


@pmiazga In my opinion the information shouldn't be duplicate (or triplicate, given it is in extension.json it could be in readme, extension.json and wiki).

IMO the AC should say: The subtleties of the config variables mentioned above are documented in the README and on mw.org. Given that the docs of config variables in the code are in extension.json.

@pmiazga we discussed your concerns in earlier comments and decided to have documentation in one place. I should have updated the description though (I'll do so if you don't oppose strongly).

pmiazga claimed this task.Apr 25 2017, 2:53 PM
pmiazga updated the task description. (Show Details)

Ok, sounds good, let's keep all information in one place. I removed "storing information in codebase" from AC, now everything is done. I'm marking this task as resolved

pmiazga closed this task as Resolved.Apr 25 2017, 3:49 PM
pmiazga moved this task from Needs More Work to Ready for Signoff on the Reading-Web-Sprint-96 board.