sinara-hw tidying up - Githubissues

dtcallcock commented 5 years ago

It's really great that Sinara has its own organisation and sensible repository structure now. Thanks to everyone who made that happen. However, I think a few small changes could make it less intimidating and easy to navigate for people new to the project. Here's a few suggestions:

[x] Make a website and landing page for the project using Github Pages. This page could be fairly static, just giving an overview of the project and pointing people to the wiki etc. In any case it should be no harder to maintain than the wiki as it can be written in markdown and live on GitHub.
[x] Move relevant wiki pages from Sinara to meta, delink the depreciated pages for individual boards and link the new board wikis.
[x] Make it clear that the Sinara repository is mainly depreciated except as a place for the Sayma issue tracker.
[x] Make sure every repo has a readme file that give a description and points people to where the action is (Issues, Wiki etc.).
[x] Address anything left in and/or close this issue: https://github.com/sinara-hw/sinara/issues/208

I am happy to pitch in with this. Also happy to leave some of this if there's a reason for how it is right now.

gkasprow commented 5 years ago

It's here https://sinara-hw.github.io/

dtcallcock commented 5 years ago

Thanks @gkasprow

I was hoping we could use the built-in Jekyll integration so that the website can be in markdown instead of html. If you give me write access to the sinara-hw.github.io repository I will set it up (the initial setup looks tricky to do with a pull request). You can see if you prefer it to the html and if not you can revert.

gkasprow commented 5 years ago

Done. I didn't know about JekyII. I did what was suggested on Github Pages :)

dtcallcock commented 5 years ago

I made a simple Jekyll webpage with the information I thought would be useful to somebody coming across Sinara for the first time. People should feel free to iterate.

@gkasprow can you make https://sinara-hw.github.io/ the website of the sinara-hw organization so that the link appears at the top of the page for people who go directly to https://github.com/sinara-hw

dtcallcock commented 5 years ago

I rebuilt the wiki at https://github.com/sinara-hw/meta/wiki including moving all the images over so there aren't dependencies on the old Sinara repository. Most of the links are fixed too but I don't have access to the dio_bnc, mirny and VHDCI_Carrier repositories so couldn't fix those (can you give me access @gkasprow). I cleared out a bit of cruft but I didn't want to touch the stuff I'm not up to speed on (mostly uTCA stuff).

gkasprow commented 5 years ago

done

dtcallcock commented 5 years ago

@gkasprow As part of the effort to drive new people to the right places would you mind doing the following if you have a second:

Pin the 'meta' repository to the top of the organisation's page. See: https://twitter.com/github/status/791759883800571905?lang=en
Change the description of 'sinara' repository from 'Hardware designs for the ARTIQ DRTIO ecosystem (Sayma, Metlino, Kasli)' to something like 'Sayma issue tracker'
Move the tags from the 'sinara' to 'meta' repository (or just delete them).
Add a description of the 'thermostat', 'mirny', and 'VHDCI_carrier' repositories and delete the empty 'booster-circuit' repository.

marmeladapk commented 5 years ago

Just a heads-up: GitHub recently added an option to move issues to other repositories: https://help.github.com/articles/transferring-an-issue-to-another-repository/

hartytp commented 5 years ago

@gkasprow I've talked to quite a few people in other institutions who are potentially interested in Sinara hardware, but are currently put off by a lack of documentation. I get questions like: these cards seem nice, but what do they do? how do I find information about them? where do I buy them? what are the specifications? how much do they cost? do they really work? Which boards are prototypes and which ones are production ready? What's the level of software support? Where is the website for them (I saw the old page, but all the links seem to be broken)? etc

Part of the answer to this is more help from the community to improve the Wiki. In particular, "case studies" showing examples of how people are actually using these in experiments would be a great help.

However, now that Creoteh are commercialising these boards, I wondered if they would be interested in helping to provide documentation. It seems that there is a simple business case for this: the better the documentation the more cards they will sell. What do you think?

gkasprow commented 5 years ago

I know that level of documentation is poor. This was one of the reasons why we asked for money for commercialisation of the equipment. Writing decent documentation is part of it. Within this grant CTI will:

do review of project, replace EOL components, prepare for mass production
prepare automated test benches. This is already done for some modules.
write documentation. This grant is continuation of previous one which was funded to commercialise OHWR modules. Documentation example is here

Another thing is wiki. All documentation should start here and point to project resources and finally to web shop where products can be purchased. This process has already started but this will take time. I update regularly page with status of modules, but this should have more interactive form.

hartytp commented 5 years ago

That's really good new @gkasprow. Looking forward to seeing some of those docs come on line.

There is quite a lot of test data for these boards scattered through the issues. It would be great if some data like this could make it into the final data sheets.

gkasprow commented 5 years ago

I added initial wiki pages for Banker, Stabilizer and Humpback

drewrisinger commented 5 years ago

The Kasli link in this section (https://github.com/sinara-hw/meta/wiki#carriers) is broken. Points to VHDCI carrier instead. As a side note, if there's some way for the community to edit the wiki, that'd be great.

gkasprow commented 5 years ago

fixed. @drewrisinger I gave you write rights.

gkasprow commented 5 years ago

I added wiki pages , updated status for all modules.

dtcallcock commented 4 years ago

Related to the above, but spurred by comments in https://github.com/sinara-hw/Zotino/issues/24

hunting down the BOM hidden under releases

Releases is the right place to put the BOMs and pdf output files. However, nobody seems to expect that's where they would be (partially because GitHub hides the 'releases' tab pretty well). I tried to make this clear on https://sinara-hw.github.io but I don't know if there is a better way to signpost it. Like a sentence that states this at the top of every wiki page?

Wiki editing is limited to members of the sinara-hw Github group

I know this is a can of worms but would some statement somewhere about the governance/ownership/purpose of sinara-hw (or at least how to get editing rights) be useful to new people? People thinking it's some kind of closed shop or an internal M-Labs project isn't good for expending the user base or participation.

dtcallcock commented 4 years ago

Also, can you take a look at this if you get a second @gkasprow ?

Pin the 'meta' repository to the top of the organisation's page. See: https://twitter.com/github/status/791759883800571905?lang=en

drewrisinger commented 4 years ago

hunting down the BOM hidden under releases

Releases is the right place to put the BOMs and pdf output files. However, nobody seems to expect that's where they would be (partially because GitHub hides the 'releases' tab pretty well). I tried to make this clear on https://sinara-hw.github.io but I don't know if there is a better way to signpost it. Like a sentence that states this at the top of every wiki page?

We should be able to put a link to the project's release page in the base README.md on each project's GitHub page. See https://github.com/sinara-hw/Zotino/pull/25 for an example. The wikis would also be an appropriate place to put links to the design files.

dtcallcock commented 4 years ago

We should be able to put a link to the project's release page in the base README.md on each project's GitHub page.

I have now done this for most of the repositories, but lack write access to Phaser, Driver, CompactPCISerial_EEM_Adapter, Humpback, IDC_HD68_Adapter, Kasli-backplane-adapter.

Can you fix this for me @gkasprow ?

The repository descriptions are also all over the shop or missing. I'm happy to sort this out but I'd need to be elevated to administrator on most of the repositories (I can currently only edit one or two of them).

gkasprow commented 4 years ago

You have the Maintain rights now.

jordens commented 4 years ago

thanks @dtcallcock

sinara-hw / meta

sinara-hw tidying up #17