Questions we need to answer/things to be agreed on:
What is the purpose of each page? (who will access it, what are their needs)
What content should be a part of each page? (this will obviously depend on the answer to (1)
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?)
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.
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
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.)
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.
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?
Developers
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
Localisation/translators
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?
TBC
I think:
the technical implementor, and developers pages are in pretty good shape.
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.
