Better home page for the wiki

JoshCheek commented 7 years ago

Not really sure what to do with it, but the one on there makes it feel unloved. Perhaps clone it and see if there's a config file somewhere, probably the one on installation should be the default home page for the wiki.

Note that all the pages in the wiki are linked from the readme, so really the readme is behaving like the wiki homepage.

ckib16 commented 7 years ago

I can take a hack at this too if you'd like.

I've done a lot of GitHub wiki work on my repos at my job. I know the exact problem you are talking about re: README vs wiki. GitHub Wikis aren't the most feature-rich, but it's the best we've found in terms of having docs being easy-to-update while maintaining multi-page structure/organization.

For now - we've settled on putting the bulk of the documentation in the wiki, and keeping REAME fairly broad.

Maybe some first steps would be for me to:

[ ] add installation page text as wiki homepage with link from README
[ ] populate the wiki sidebar so you can order pages however you want (we use this as our 'Table of Contents')

Just let me know.

JoshCheek commented 7 years ago

That would super appreciated! I've not looked at the wiki repo at all, so IDK what is even possible. Meaning you have the authority to make whatever decisions cause these statements to be true:

It is easy for people to discover what they're looking for. Eg right now I link everything from the readme, since I think this makes it more discoverable, since I expect it's the first place someone would go if they were looking for information. If you think most people are interested in installation, then installation information should be highly accessible (note that this is my current assumption). Based on the assumption that the most accessible place it could be is the readme, you could move it there (doesn't matter that I moved it out of there). A downside of moving it there is it would be separate from the rest of the wiki, reducing the overall coherence. From that example, we can see that any decision will have tradeoffs and we can't arrive at a Correct Solution™, we can only be thoughtful about what tradeoffs we're making. There are probably 3 or 4 other ways to achieve this, maybe brainstorm it a bit to make sure we don't overlook something better.
It should feel loved. When people go there to find info, it should give them a sense of confidence that it's maintained, current, and is the best way to answer their question. Eg I manually clicked everything I linked to make sure it worked, I cross-referenced things where it made sense, ideally it would be well organized and easy to navigate / understand what page you're on at and how that fits into the wiki's structure as a whole. Based on the current layout, some love for the sidebar and homepage would go a long way here, but it sounds like you know way more about what is possible than I do, so feel free to explore the possibility space.

ckib16 commented 7 years ago

Yup - sounds great.

I'll start tackling the sidebar 1st, and we can go from there!

ckib16 commented 7 years ago

To do

[x] Sidebar with structure
[x] ~~Auto TOC - Gollum TOC syntax~~ - did not work, just showed _[TOC]_
[x] Add image to home page

Ask Josh

[x] "How to search wiki" page - see repo at work
[x] Add reference section / appendix for other code visualization tools

Maybe Later

[ ] Auto TOC - Github-wikifier?

ckib16 commented 7 years ago

Ok @JoshCheek - the sidebar & TOC are built. Along with a modified Homepage.

I'll keep this issue open as my overall "todo list" while I start migrating issues over to wiki ( #110 )

Two ideas above in my todo list that I added. See if you like them:

wiki page for how to search wiki (was not intuitive to me how GH does this, constantly got ?s on it at work)
wiki page for curating related projects like Bret Victor stuff, Swift Playgrounds. I always felt the ruby community needed a good source like this, but have not found one

JoshCheek commented 7 years ago

wiki page for how to search wiki (was not intuitive to me how GH does this, constantly got ?s on it at work)

Up to you. What info might someone be looking for, will they need a search page to find it?

wiki page for curating related projects like Bret Victor stuff, Swift Playgrounds. I always felt the ruby community needed a good source like this, but have not found one

I'm in :)

ckib16 commented 7 years ago

Good deal - I added both.

JoshCheek / seeing_is_believing

Better home page for the wiki #111