Rebuilding our Project Documentation

Governance
1

We’ve long had project docs in a Google Drive folder, whereas our product docs (HSDS etc) have been in Github and on the ReadtheDocs site.

I’ve taken a go at consolidating them into one set of documentation, all available on the ReadtheDocs site. See here.

Assuming folks think this is good, we’ll use the Drive more for misc file storage, and our primary governance policies will live in markdown files hosted on Github and displayed at docs.openreferral.org.

Let me know if you have any questions or suggestions!

2 Likes
2

Looks good to me! Is there a particular branch where we should issue pull requests? (Master, or something else?) (My speciality is typo fixes: (“conjuction” → “conjunction”)

(Added note: consider renaming Master to Main:

)

3

One more bit of feedback. Any chance of editing the menu colors? The FAQ level questions for instance:
Frequently Asked Questions — Open Referral Data Specifications 2.0.1 documentation
are failing the checker for color contrast accessibility.
WebAIM: Contrast Checker

(The result syncs with my own perception: I find that .wy-menu-vertical li.current a gray quite hard to read.)

4

Thanks Margie!

I fixed the typo, and will add the Master>Main change and the color contrast issue to our queue. much appreciated :slight_smile:

5

So this year, as described in this thread, we consolidated our Project Documentation from googledocs into our Github repo, so that it would live alongside our Specification Documentation in ReadtheDocs.

But we’ve since gotten feedback that the Technical Documentation site may be trying to do too much, in confusing ways – and the technical stewards have suggested that we try rebuilding our Project Documentation on our OpenReferral.org site. This would at least keep us at only two documentation places, down from three (Wordpress, Google Docs, Github/ReadtheDocs) – and it means that that everything about the project is found on the organization’s website while the ReadtheDocs site is just dedicated to technical specs for the product.

I’ve started testing that process out:

I’m eager to hear feedback from the community on this. Do you agree that the Project Documentation should belong on our main organizational website, separate from the Product Documentation on ReadtheDocs? How might the Project Documentation be improved? Etc.

Thanks!
greg