What else do you want to see from common-readme? about common-readme HOT 9 CLOSED

FWIW, standard-readme is a yeoman module (pretty sure you worked on that too, @noffle).

from common-readme.

Hi. I don't actually use this yet, I watch repos that I want to come back to because they interest me, and maybe eventually start contributing. I'll go ahead and read some of the content on common-readme more in depth here in a bit. I like the idea!

In relevance to your questions, I use this scaffolding tool called generate with generate-readme. It's pretty new so you may or (more likey) may not have heard of it, but so far is basically everything I wanted yeoman to do, so I've enjoyed it. I might be interested in making a generator for that, but it would be my first one and also for another project I'm new to.

from common-readme.

Or perhaps we could see if generate-readme wants to adopt common-readme practices.

from common-readme.

I like the ideas that you have listed currently. I'm not sure if you intend for these rules to be copied into other programs though, as it seems some of it is orientated around this being a tool in itself.

I think if you want to make something common, you'll have to make it "spreadable":

1. Have badges or a way to promote that links back to this project, so more people discover it.
2. Define some clear rules that can be copied into multiple different tools.
3. Create a bunch of plugins people can adopt into their own systems, so it doesn't disrupt their workflow.

Maybe standardjs is a good example: badges, clear rules, multiple plugins, etc... But I'm not sure if that is what you are after with this project, just some ideas. :)

from common-readme.

(Btw, I believe I've seen you reply on email before. I edit my messages a lot, bad habit)

from common-readme.

Wow! Hey, thank you @jamen for your thoughts. I took so long to respond not because I didn't see your messages, but because you gave me a lot to think about. What is the purpose of the module?

Having link-backs is smart. Currently the template.md file contains a link to this repo under the See Also section. I have mixed feelings about badges (see number 5 from here).

I'm not sure if you saw, but this module is also a README generator for common-readme styled READMEs! I'm not sure if porting it to other generators is valuable or not.

I'm realizing that I'm leery about the idea of common-readme as a "standard" or "system". This seems better suited for something like @RichardLitt's standard-readme, which does a much better job of tackling the topic of READMEs from a more systematic angle.

I'd like common-readme to be about education. If art of readme is a style guide, then common-readme is its physical realization. A tool to put a style guide into practice.

What does this mean for this module? I'm not sure. Maybe it's just fine as it is. Maybe I'm happy if someone just reads this, thinks about its ideas, and starts using the ones they like in their own documentation. Maybe that's enough.

from common-readme.

What I'd like the most is to simply get more people trying out the generator tool and seeing if it's helpful or not. This might be more of a marketing problem than anything else.

from common-readme.

I actually had not seen that art-of-readme repo, looks awesome! I'll give it a more thorough read-through soon.

Your idea for common-readme being more educational than anything sounds interesting, but I feel like (at least for me personally) it wouldn't reach much beyond a beginner audience, because people might move on to other generators or tools as they discover them. But, if you think it at least leads them down the right path, and they may/may not use it as their main tool for READMEs, then that is good enough in my opinion.

That might be a biased viewpoint, because I've used scaffolding tools for a little while now. I like how they provide something like common-readme, except under an ecosystem with lots of other cool generators, and they all work together nicely. (compared to individual tools, with varying dependencies for things like prompting. feels a little harder to use them together)

Otherwise, I think something like standard-readme or art-of-readme as you point out would be great.

from common-readme.

Fair points. I like the idea of folks deciding to add common-readme to other generator ecosystems; though I'm not sure that requires any action on our behalf -- I suppose it'll just happen if folks want it.

from common-readme.