Documentation Working Group Meeting 30th Nov

2021-11-16T15:00:00Z2021-11-16T16:30:00Z

:tv: Google meet room: https://meet.google.com/iox-rgnw-jhg

Agenda

  • :writing_hand: - Who will take notes? :raised_hands:
    • To take notes, all’s you got to do is press the EDIT button on this post.

Documenting Hypha Customization options

  • Would love a recap of conversation from Adopter’s meeting (esp. referencing @kfogel’s comment here)

  • Github link to recent commit

  • What of this should be added to User docs?

  • Translation/localisation

    • How can organizations get started translating org-specific terms?
    • @frjo mentioned in the last Maintainer’s that Localisation Labs might be the first step, can we get more information?

Updates on assigned docs pages from wider docs WG

  • Eriol on Make "How to contribute" to documentation page · Issue #22 · HyphaApp/hypha-docs · GitHub
  • Dan on the “Learn More” section, which contains:
    • About/Overview
    • Background/history
    • Features
    • Stakeholders
    • Governance
    • (Adopters)
  • Emily on:
    • Gitbook - Github mirroring: I want the organization in the Summary.md file–which dictates docs structure in Gitbook–to match the structure of the github repository - how do I do this?
      • Any insights from Maintainers call re: what needs to be done to change github repo structure?
      • this will be a big change, and we’ll need to make sure folks like @maxpearl or anyone who keeps a clone of the repo on their personal machine is aware of the change as they may want to…what? Re-clone repo?
    • Generating a list of specific sub-pages in my sections (Getting Started, Applicants, Fundees, Reviewers, Staff, Administrators) - I’ll create blank “How-to” pages relevant for each type of user, and a brief summary of what I expect will go in there
      • What are folks’ thoughts on something like the “Login” page - do we want to duplicate that three times, or does it belong in “Getting started” (only difference is what your login screen looks like) - right now it’s called “First Steps” but I actually think it should be its own page with “Logging in” because with the screenshots, it’s a big enough page to be a standalone topic
    • Generate github issues for creating each of the above sub-pages
    • Remove “under construction” banners for mostly completed docs
    • Make the docs PRETTIER so they easier to navigate/read/process) - examples of very easy to read docs? (most example doc pages we currently have use headers to delineate info, which can be tough for me to read, but Decidim’s pages are nice - using tables, for instance)

Other topics folks want to discuss?

  • We need to do a better job documenting who is responsible for different aspects of Hypha’s development . Some of the info exists on the Hypha main page and the main documentation page, but we can make more explicit the division of labor (in the sense of saying “here’s who to contact if you have questions about:”). It might also be a good idea to list the means by which we can contact each of those folks (perhaps a link to WeChat and their handle on the platform).

    • EC comment: this is what the Stakeholder’s page is supposed to do. Let’s agree on where it fits in our new organization–we’ve currently said it falls under @blah’s purview under “Learn More”–and I’ll move it there/make it live
      • Speaking of this, page, can we review it for content (since each of us is on there, so we agree with wording of our roles, contact preferences, etc)?
  • General Doc org/labeling:

    • Added descriptions to some of the roles in Hypha Documentation Organization spreadsheet
      • Can we clarify who we mean by the “Administrator” (specifically how it’s different from Staff and Developer, maybe my description of “Developer” is incorrect)
    • Also, what about changing “Learn More” to “About Hypha”?
  • New developer docs person?

  • What kind of Meta-Analysis of Hypha docs could be done?

    • EC added: And at what point would we do it?
  • What would user-testing on documentation look like?

  • OTF’s Happy Hour docs

  • Dev updates and where they are logged for adopters/future adopters

    • Fredrik updated a dev task on the 5th of Nov where the task: ‘Choosing a project approval form which has never been used has been removed from the core codebase in Nov 2021’ - No Adopters were using this function but Eriol is wondering if the docs team should/could have a wiki page(?) where changes like this are logged outside of the Github PR’s so that Adopters can understand what’s happened.

Edit where you need to :slight_smile: @emlini

Edited–looking forward to tomorrow’s meeting!

Couple of things I’d like to raise in the Maintainer’s chat, but I didn’t see the post for that so I’m putting them here for now:

  • Issue: How to make github hypha docs repo organization match Gitbook organization - basically, is there a way to get the organization from the SUMMARY.md file to be “pushed” to the github repo?

  • Possible solutions for this:

    • Revise folder organization in Github (creating new folders) or via my local copy, any problems with doing this, @frjo?
    • Create totally new “hypha-docs-gitbook” repo and do an initial sync FROM Gitbook - issue with this is having to re-create all the existing doc pages that @maxpearl (and others?) already created (just copy-paste, but annoying)
    • Other possible solutions?
  • Less-important question (relevant for page edits I’m doing): Can reviewers communicate with applicants directly?

    • There is a “Communications” tab for each project a reviewer is assigned to, a text box to type a message, and a “Visible to” setting that has the options “Reviewers” and “All” – are “applicants” included in the “All” group?
    • If not, is there another way Reviewers can contact Applicants directly (other than via the Applicant’s email, which is listed on the Project page for the Reviewer to see)?
    • Do all adopters want Reviewers to be able to contact applicants directly? Is it (showing applicant email to reviewers, or allowing reviewer-applicant communication) a customizable setting?
    • Is this the kind of question I should post on we.hypha.app?

@bernard says Applicants are included in the “Visible to: all” setting.

So this leads us to this question:

  • Do all adopters want Reviewers to be able to contact applicants directly? Is it (showing applicant email to reviewers, or allowing reviewer-applicant communication) a customizable setting?
  • @bernard says there is a way for applicants to not be visible to reviewers, but doesn’t remember how/where it’s done.
  • @dluong, do you remember whether this is the case? And if so, how we do it?

I’m going to add this question for adopters to the Adopters meeting agenda tomorrow.

@emlini we can add the ‘visibility’ option to review forms. Here it is on the 1) review form and 2) in the WagTail Admin:

Review Form

WagTail Admin field in review forms

1 Like

GitHub shows how the markdown files are organised in directories. If you clone the repo this is how it will look on your computer.

The SUMMARY file tells GitBook how the render the content. There is no correlation between them. If one want these structured in the same way, to make it easier to find stuff e.g., it needs to be done manually.

1 Like

Thanks, @dluong! Couple follow-up questions:

  • Does this ‘visibility’ option apply to a field (within a Form, Fund, or Round)? Like can you make the “applicant email” field specifically “private” (without making the rest of the application private)?
  • It seems like the only options are to make it (the field or whatever this setting applies to) either totally Private (except presumably to Staff Admin), or visible to Reviewers AND Staff–is there a way to make it visible to Staff but not Reviewers?

@emlini maybe you’re inquiring about the comment section? The functionalities are there to give users options as they administer different funding approaches. Hypha is more like clay than marble.

A participatory funding approach may want reviewers to have access to each other’s reviews and communication.

Hi @dluong @emlini and others. Just noticed the discussion on visibility and communications between reviewers and applicants. DFF’s process is set up so reviewers are meant to be anonymous to everyone except staff. Applicants should not know who is reviewing their application. And reviewers shouldn’t know who else is reviewing applications. We also don’t want reviewers and applicants talking to each other, or even one reviewer talking to another reviewer (and they shouldn’t be able to see each other’s reviews). When we set up Hypha, we had to make some changes to implement this. @allan can probably say more about that if it is helpful.

1 Like

@emlini I had missed to add GitBook to the list of users that are allowed to commit to the main branch in GitHub for the docs. Fixed now.

@emlini Field visibility has been discussed but not implemented yet.

@emlini You have visibility settings for two different things as @dluong takes about above.

  1. Reviews, allowing the reviewer to set the review they are writing to private (only staff) or public (other reviewers).
  2. Comments, allowing a user to set who should be able to read the comment they are posting.

@vinkthom reminded me this morning that there is a feature within WagTail if you go to Setting > Reviewer Settings to select what reviewers can access from other reviewers.

Step 1:
Screen Shot 2021-12-02 at 10.29.42 AM

Step 2: