Create interactive readme template generator
davidak opened this issue · comments
The current editable template is a great start. It's right there and you just have to edit it, like you do with your README.md in your editor. (That's a little nerdy, but not elitist, so i would keep that design. I think programmers love it!) You don't have to install anything and have a preview next to it.
We should extend it in a way so it still feels this lightwight.
I like the idea to have sections that a readme should have and optional ones. A text above the section descriptions should explain that.
I also like to have a common section order that a readme should follow. This spec is a good starting point.
I suggest a design where you can enable and disable sections with switches like these. sections a readme should have are enabled by default. When enabled, the new sections appear in the editor box. A section consists of it's heading and everything until the next section heading including an empty line. When you disable a section that you already edited, the content should be saved locally, so it's added again when re-enabled.
Reloading the site or using a reset button resets the template editor and section switches.
I'm not a designer or UX specialist, so i would like to hear the opinion of one. I'm also no JS programmer, so i will not implement it. There is probably someone who would like to do that.
Here are different Examples:
What do you think so far?
Yeah, that all makes sense to me. I like the idea of toggling sections on and off. I can implement it, but getting the UX right will be a challenge.
It might be worth it to make the generator a separate page on the website rather than trying to squeeze it into the existing example. So the homepage would be dedicated to teaching, and this new page would be dedicated to creating a new README.
I think it is important to have this on a single page when possible. The usabillity should not be compromised by too many features of course!
I'm about to ask @opensourcedesign if they know someone who want to help to design a good UX for this. What do you think about collecting money to even pay (a little) for this? My financial situation is very bad right now, but i would throw in 10€.
Any particular reasons why you think it's important for everything to be on a single page? My concern is the possibility of overwhelming new users.
I think we can get away with either finding someone who is willing to contribute a design for free or working at it ourselves until we are happy with it. I appreciate the offer, but you should keep the money for yourself.
First of all, I'd like to point out a project that became quite popular recently, which does exactly what @davidak seems to be proposing: https://readme.so/editor
That said, I do prefer the simplicity and well-roundedness of the make-a-readme website, so I'd still add my support for this feature.
I definitely sympathize with @dguo's concerns regarding overwhelming the reader with a complex interface. But perhaps something relatively simple could be done. Here's a quick proof-of-concept I whipped up using my browser's inspector tools, just to get a feel of what it could looks like:
And here it is with a narrower screen, which shows that it can work well in a responsive manner too:
WDYT?
(Of course, in the background this would imply additional complexity, e.g. to avoid losing manually edited text when a section is toggled off; but that wouldn't impact the actual UI's simplicity, so IMO it would be best to discuss those concerns once a UI approach is agreed upon.)