Enhanced `README.md` files about central HOT 23 CLOSED

Hello :)

Nice changes 👍

I think that help badges must be put after the build / coverage / packagist badges. They are the most important for me on a README.

I also think that putting help badge below the library title will make the file header more readable.

I don't think that there is too much badges but, too much at the same place 😄.

For me 👍 for all the others points !
I can make the change on devtools:documentation command if you want.

from central.

With the “Related projects” Section, https://github.com/Hywan/Ruler/tree/readme#related-projects. What do you think @hoaproject/hoackers?

from central.

Here is a new version with a center aligned header, https://github.com/Hywan/Ruler/blob/readme/README.md.

If everyone agrees, I will start merging them, even if Travis CI and Coveralls are not setup yet. Thoughts @hoaproject/hoackers?

from central.

That should be good to include also "Snippet" section beside documentation no ?

from central.

When we will have snippets. We don't have any yet.

from central.

Thanks,
But for me before having a complete readme, I think when you create a new repository it should have at least two elements : a license file and the description of the project in the readme.

When the project is more advanced, adding the full readme.

About this readme (the main idea of this issue), a link to the awecode is a really good idea. Adding link to travis or other tool like this can also be interesting.

For the "Related projects" section, for me it's more in the documentation page that it should be.

from central.

Updated my first comment according to hoaproject/W3#55.

from central.

@Hywan I think adding a section about how to run tests woulb be great to ease contribution.

from central.

@jubianchi it's in the contributor guide, not enough ? http://hoa-project.net/Fr/Literature/Contributor/Guide.html#Testing_a_patch

from central.

@osaris this page is perfect and should be linked in every readme IMO

from central.

@jubianchi +1

from central.

@jubianchi Ok.

from central.

Hello :-),

So, here is the new proposal for the README.md file: hoaproject/Ruler#88. You can view the current (it can be outdated very quickly) proposal here https://github.com/Hywan/Ruler/blob/4210e10908c94fa91f4c26a44be7b8571810b4ed/README.md.

Here is whats' new:

• New logo in SVG,
• The state badge (beta, finalized etc.) has been removed,
• New badges:
  • Help on IRC,
  • Help on Gitter (directly on Central),
  • Documentation,
  • Board,
  • Build status,
  • Code coverage score,
  • Packagist,
  • License,
• “Learn more” link after the abstract/introduction, pointing directly to the hack book chapter,
• Rephrasing of the “Installation” Section, because we need to say Hoa can be installed with something else than Composer,
• New Testing Section, promoting the contributor guide for more information,
• Rephrasing of the Documentation Section, promote the Hack book, explain how to generate the documentation locally,
• New Getting help Section, explaining how to join us on IRC and on Discourse,
• New Contribution Section, promoting the contributor guide,
• Rephrasing a little bit the License Section,
• All links to Hoa have been updated with HTTPS.

Questions:

• Too much badges?
• composer require hoa/ruler ~3.0 instead of a JSON sample for the Installation library? We need to specify the version, else Composer will add ^x.y.z format and this is not what we want,
• New option to generate the documentation, devtools:documentation --open,
• Maybe we can make a smarter default value for the --directories option of devtools:documentation in order to remove this option in the README.md (just like we did for hoa test:run --directories ., cc @shulard),
• I ask to @Pierozi a new redirection from users.hoa-project.net to discourse.hoa-project.net, again for maintainance of the README.md files.

Thoughts?

from central.

@shulard About devtools:documentation, yes, please do! I have created an issue for that, hoaproject/Devtools#32.

Can you also review hoaproject/Devtools#31 please?

from central.

@Hywan It's look good like this, maybe the logo are too big ? 150px should enough.

The state badge has been removed but do we keep the process of beta, rc, finalized ?

I think the section Related projects it still a good idea to promote each others.
we can put it with a some words like, Open an issue if you use this library for tell us why you have choose it and link to referred the project.

from central.

👍 for the related project section + links. Yes, the beta, RC and finalized states are kept (in the .State file).

from central.

@shulard If we put the help & doc' badges bellow the library section title, then what is the meaning for the other badges (build, coverage etc.)? They are all related to the current library. I understand we should split them but I am not sure this way. Do you understand my issue? If yes, do you have another idea or an argument?

from central.

Current page: https://github.com/Hywan/Ruler/tree/readme.

from central.

@Hywan, I understand you issue.

For me the first line of badges is related to documentation so their place is under the title. Then the others represent the state of the library which is important as the first information to be viewed by the developer.

I don't know if it's the right way to go but it's what I read/search first when accessing to public code 😄.

from central.

New version: https://github.com/Hywan/Ruler/tree/readme.

from central.

Really great !

FYI, I've seen you put https link for users.hoa, but it was only configured in unencrypted mode, i've update config for redirect https too.

from central.

@Pierozi Actually, users.hoa, so discourse.hoa does not support HTTPS. It's HTTP only so far.

from central.

Done!
Next step: Write missing README.md. In another issue.

from central.