search

freedomofpress / securedrop

GitHub repository for the SecureDrop whistleblower platform. Do not submit tips here!
https://securedrop.org/
Other
3.62k stars 687 forks source link

Consider consolidating public GitHub wikis #6552

Open eloquence opened 2 years ago

eloquence commented 2 years ago

Currently we have multiple wikis used for dev info:

I would suggest we consider consolidating all four of these wikis under securedrop. We should be able to create an internal structure in the wiki (e.g., using page title conventions), which would reduce the need to do cross-repo hopping/searches.

There's a fairly large UX wiki as well here: https://github.com/freedomofpress/securedrop-ux/wiki

I think we should consider that out of scope for an initial consolidation, but consider whether it makes sense to keep it separate in the long term.

eaon commented 2 years ago

Rather than the separation by repo, my main gripe is with GitHub wikis in the first place. I've hardly ever used them, even passively. The biggest problem for me is discoverability.

Consolidating the page data would hardly help with that. Taking care of more self-hosted (and in this case: publicly accessible) infrastructure is a drag, but really for something as critical as on-going information sharing for the team and community I'd much rather use something that doesn't feel like a bolt-on-afterthought.

eloquence commented 2 years ago

That's a fair point; I'm also not a big fan of the GitHub wikis. I have in fact been using the git log method as a recent changes replacement - being able to clone the wikis like a repo is probably the only thing I like about them :P.

I do think consolidating now could have some advantages in discoverability, but it would be a fair bit of work to canonicalize titles in a way that helps, so I'm also happy to not do that work if people don't think it'd be an interim improvement. Setting up a new public wiki is certainly not off the table but would probably have to wait until other infra projects we've been working on are completed.

zenmonkeykstop commented 2 years ago

Seconding Michael's points, github wikis are kindof basic and not where I would choose to build a single source of our repo docs.

If one of the motivators here as expressed offline is to make it more obvious where meeting/discussion docs are, maybe a compromise would be to have a policy (noted on each wiki's home page) that:

erinmikailstaples commented 2 years ago

Hey folks!

New to contributing to this project, but happy to jump in and help out here on this one. :)

If building a wiki — I do like what @eloquence brings up as far as being able to clone the wiki. As a new contributor to this project and looking to get more involved, I do agree that having one place for all wikis or docs is really nice to be able to scroll through and catch up on various projects and being able to set them up.

Not sure what the internal org hierarchy is, but happy to help on simply organizing and consolidating the docs here in the interim if that would be a hand.

Please let me know if that would be a helpful as y'all decide what's next!

eloquence commented 1 year ago

Thanks @erinmikailstaples for offering to help with this! <3 Perhaps one way to start would be to inventorize (e.g., in a GDoc or similar format) some of they key pages/page hierarchies by repository, and offer any notes/recommendations based on your own observation (e.g., "This page is outdated", "Just a link - can be deleted", "maybe move to SD wiki") in line with the principles @zenmonkeykstop outlined in in https://github.com/freedomofpress/securedrop/issues/6552#issuecomment-1252448255 - what do you think?

erinmikailstaples commented 1 year ago

This sounds great to me, @eloquence — I'll jump on this first thing tomorrow, had a bit of stomach flu that held me out.

stay tuned! Looking forward to this one!