Organizing Hypha index pages

New topic, at @frjo’s request, about the purposes and content/organization of the index pages we have for Hypha.

As I understand, there are three pages:

Questions we need to answer/things to be agreed on:

  1. What is the purpose of each page? (who will access it, what are their needs)
  2. What content should be a part of each page? (this will obviously depend on the answer to (1)
  3. Where will answers to / decisions regarding these questions live after we’ve hashed them out in this forum? (possibly on the great miro board @bernard created laying out the architecture of the first two sites?)

Have I covered everything?


@bernard ideas here Link to documentation on - #7 by bernard are a very good start I think, maybe you can paste them in here?

The Hypha site is a broad introduction for anyone with links to documentation and GitHub. I would really like to see a screencast or similar here showing of Hypha in the future.

The GitHub README is for developers. It should explain what the system is about, who is behind it and have links to documentation etc.

All roads then leads to the documentation site. This is for really interested people and most importantly for users of Hypha that needs to get stuff done.

I’m really happy that Hypha documentation is taking shape! It will greatly improve the users experience. It will also help improve Hypha itself, if something is hard to document it is most likely hard to use and need some redesign.

1 Like

Thanks for raising this here @emlini and also awesome to see docs growing! +1 to docs index focus being on docs layout/structure and also how to get help. great example to me is Django documentation | Django documentation | Django

1 Like

Thanks for this example–I’ve been hoping to solicit documentation examples folks really like, so I can model Hypha’s documentation on them.

I’ll summarize some of the things folks have said here, but I’d love to have the info in a place where we can easily edit/update it according to comments. My mind goes to “Google Doc” but are there better suggestions? (It occurs to me that the miro board, though awesome for site architecture, may not be the best place for the amount of detail we want to include–or maybe I’m just not familiar enough with how to use it)

(A) Hypha site index page

  • PURPOSE: high-level introduction to Hypha
  • USERS: Anyone (can/should we specify types of users in more detail?)
  • CONTENT: The stuff that’s on the page now + possibly a screencast Hypha demo (@frjo’s suggestion, I like this)

(B) Hypha documentation index page

  • PURPOSE: instructions for using Hypha
  • USERS: adopters, potential adopters, people tearing their hair out trying to figure out how to do something
  • CONTENT: @blah and I both made edits to this, see new version here.

(C) Hypha github repository README page

  • PURPOSE: house code for Hypha core & issues list
  • USERS: developers/maintainers & deployers for organizations who adopt Hypha
  • CONTENT: system overview, maintainer info, links to documentation

(A) Hypha site index page

I think we can remove the sections “About the Hypha team” and “Support Hypha”.

This page also should be made to look nice.If someone can suggest a nice look for the page I can implement it. Producing a nice screencast will take time but some screenshots maybe, and some colour?

(The current look is the my Zen theme for Hugo, it is a solid base theme but not ment to be used without some nice custom styles.)

Proposed new IA for documentation

(See the original on the Miro board)

Assuming no objections, I want us to organise the current development under a contributing page which includes other ways to contribute. Development is not the only way to contribute to an open source project.

1. Hypha site index page

Link: Hypha site index page

What is the purpose of each page?

still workng on this

What content should be a part of each page?

still workng on this

2. Hypha documentation index page

Link: Hypha documentation index page

What is the purpose of each page?

To provide detailed information to the 5 user types below, so they can get started with Hypha.

Who will access it? What are their needs?

Technical implementors
They need:

  • an overview of technical aspects of hypha
  • hypha security (audit history and outcomes)
  • how to upgrade hypha
  • how to administer hypha
  • how to maintain hypha
  • how to deploy hypha
  • something else?

They need:

  • how to contribute code to Hypha
  • something else?

(These pages do not exist, but I propose they are created)

Documentation writers
They need:

  • how to contribute to Hypha documentation

UX Designers
They need:

  • how to contribute UX design to Hypha

They need:

  • how to translate Hypha

Staff (who are using Hypha for their work) from organisations who have adopted Hypha
They need:

  • general information about how Hypha whitelabel works. It will be a beginning for the adopting organisation if they want tocreate their own documentation. i.e.This information will not be tailored to their organisation.
  • something else?

What content should be a part of each page?


I think:

  • the technical implementor, and developers pages are in pretty good shape.

@allan @maxpearl @kfogel @frjo anything you’d add?

  • the documentation writer, designer, localisation pages don’t exist so they need to be added. I think their needs are similar - essentially how to get started on contributing.

3. Hypha github repository README page

Link: Hypha github repository README page

What is the purpose of the readme page? Who will access it? What are their needs?

It will be:

  • the same as the index page of
  • a pointer to each section in the docs.

Where will answers to / decisions regarding these questions live after we’ve hashed them out in this forum?

The miro board is a good place to have this organised. And the changes will then be made in the git repo.

Derp - I was writing this post and didn’t refresh to see the additions by @emlini and @frjo. :man_facepalming: