hoaproject/Central

Enhanced `README.md` files

Hywan opened this issue · 23 comments

Hywan commented

Related to hoaproject/ActionBoard#17.

Hey :-),

Here the proposal (based on hoaproject/Ruler#58 and more). The README.md files are the homepages of libraries. So far, we have the following sections:

  • Abstract/short description
  • Installation (with a link to Rush),
  • Quick usage,
  • Awecode (if at least one exists),
  • Documentation,
  • License.

The proposals are the following:

  • Better documentation body, with a direct link to the hack book (even if not available/written yet?),
  • Links to “related projects”. Just like the Awecode section, it could be great to have a list of projects that use a specific library. For instance: Hoa\Ruler is used by RulerZ or ownCloud, Hoa\Dns is used by ec2dns. Also, these links should be added in the hack book chapters.

Why do I think “Related projects” is a good idea? Because it will create kind of a “Hoa network”, like the “trusters”. Also it will provide a better visibility, and most importantly: It provides examples of how to integrate this library into real “industrial products”.

Thoughts on these proposal?
Any other proposals?

/cc @hoaproject/hoackers

Progression

  • Acl,
  • Bench,
  • Cache,
  • Cli,
  • Compiler,
  • Consistency,
  • Console,
  • Core,
  • Database,
  • Devtools,
  • Dispatcher,
  • Dns,
  • Event,
  • Eventsource,
  • Exception,
  • Fastcgi,
  • File,
  • Graph,
  • Http,
  • Irc,
  • Iterator,
  • Json,
  • Locale,
  • Log,
  • Mail,
  • Math,
  • Memory,
  • Mime,
  • Model,
  • Notification,
  • Praspel,
  • Promise,
  • Protocol,
  • Prototype,
  • Realdom,
  • Regex,
  • Registry,
  • Router,
  • Ruler,
  • Serialize,
  • Session,
  • Socket,
  • Stream,
  • String,
  • Stringbuffer,
  • Test,
  • Translate,
  • Tree,
  • Ustring,
  • View,
  • Visitor,
  • Websocket,
  • Worker,
  • Xml,
  • Xmlrpc,
  • Xyl,
  • Zformat,
  • Zombie,
  • .
Pierozi commented

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

Hywan commented

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

Grummfy commented

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.

Hywan commented

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

jubianchi commented

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

jubianchi commented

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

Hywan commented

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?

shulard commented

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.

  • 👍1
Hywan commented

@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?

Pierozi commented

@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.

Hywan commented

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

Hywan commented

@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?

shulard commented

@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 😄.

Hywan commented

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

  • 👍1
Pierozi commented

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.

Hywan commented

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

Hywan commented

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?

  • 👍1
Hywan commented

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