Page MenuHomePhabricator

Documentation: FR-Tech team consensus for decisions required for next steps, topics/subtopics and roadmap
Closed, ResolvedPublic

Description

To more forward with our documentation overhaul, it seems there are a few important decisions that it'd be great to get team consensus on:

  • Which wiki, where wocumentation won't wither and wilt (T291878, now a subtask of this one).
  • On whichever wiki we choose, what should our base prefix and main entry point/summary page be? While this can change in the future, it'd save us time if it doesn't. Options might include "Fundraising/Technology", "Fundraising/Engingeering", "Fundraising", "Fundraising Tech, "FR-Tech"... (Note that this is for public documentation for engineers who work on the stack, not external-oriented "team presentation" documentation.)
  • What structure of topics and subtopics will we use initially? While this can and should evolve, it'd be great to have general agreement on our starting points. An initial proposal is here.
  • What will the initial, short titles of the main topic areas be? It seems likely that the main topics will also have their own summary pages, and will also be prefixes for more detailed documentation within those topics. For example, if the base prefix will be "FR-Tech", then we could have "FR-Tech/Donor-facing endpoints" as the summary for that topic, and then "FR-Tech/Donor-facing endpoints/Payments wiki" as a subpage/subtopic within that. As with the base prefix, these can change as we go, but it'll be a bit of pain if they do.
  • Highest priority next steps. Stub out main topic summary pages? Complete the review of existing documentation? Document flows of PSPs currently in use? More detailed deploy instructions?
  • Medium-term roadmap. What do we expect might come next, after the most urgent things are done, and how can we integrate this with the rest of our work?

Hope this is helpful! Thanks!!!!

Event Timeline

Hi! Here are the results of this discussion:

  • We agreed to put public documentation for FR-Tech engineers on Wikitech, except for documentation of Mediawiki extensions, which should go on Mediawiki.org.
  • We worked together on the proposed outline of documentation topics and subtopics, and use sprint-name-chosing-style voting to work out a few disagreements. The results are here.
  • We discussed which documentation tickets are highest priority. Ordered by number of votes received (most votes first), they are:
    • Document Adyen Checkout T288403
    • Document Ingenico T291874
    • Complete review and coding of existing documentation T291879
    • Move existing doc into new structure
    • Complete doc for deploying to the cluster
    • Create stubs of top-level topics, with links from main page, and red links to subtopics from top-level topics
    • Figure out how to get things deleted
    • UML activity and sequence diagrams for all processors T141617
    • First drafts of general overview and top-level topic overviews

For the last subtask (medium-term roadmap) we decided to just discuss as we go on T209872: epic: frtech onwiki documentation overhaul.

Also, here's the etherpad we used to discuss this.

XenoRyet set Final Story Points to 4.