New "getting started" and reorganization of README.md

[fhocutt]

• Reorganized to put important information at the top
• Added more information about dependencies and repositories
• Added a "getting started" section with information on Maven
• Miscellaneous rewording, typo fixes, etc.

[eldur]

Hmm do you think it is realy more important to know about the inner design goals and where to downloand binaries of jwbf as a code sample?

I tried to organize the README.md more like an product page you can find in eCommerce:

Amazon:

## Name of Product
>>> author/manufacturer/...
- [product image]
product details

README.md

## Name of Product
>>> short description / status badges
- [code sample]
product details
... Dependecies/Binaries, API details, JavaDocs, Refs., ...

[fhocutt]

@eldur:
Re: organization, I now agree that the design goals don't belong up at the top. I actually think that they would fit better into developerDocs.md when I write that, because they have information on the thinking behind the framework design.

I am approaching the README structure from the perspective of someone who is not sure if or how they want to use this framework instead of another. If it is confusing, they will probably give up and go find something that appears more likely to work for them.

So, the structure I aimed for without the design goals:

• basic description of what jwbf is and what it does
• information an experienced dev could quickly get started with (repositories, docs, project homepage) so they don't have to scroll past
• separation by language: a Java dev is not going to be interested in Scala sample code
• from there, go down the list of steps an inexperienced dev would take: start a project, include dependencies, and get started with sample code
• other resources at the end

Does that make sense?

[fhocutt]

TODO: add a table of contents as at the beginning of this document: https://raw.githubusercontent.com/zachallaun/datomic-cljs/master/README.md

[eldur]

My structure design is written from a perspective of an experienced developer. Someone with an idea to work or to change mediawiki based content automatically.

The most interesting part for such a person, is IMHO, partially the point you've named "Code uses idioms appropriate to the language the library is written in" so I would prefer a code example at the begining, like a teaser.

Dependecy managment, remote respositories, where to download binaries ... are details, because they are optional to check api readbility. Your structure makes sense, if someone desides that the code example looks interesting and want to know more details.

Compare with: http://junit.org/

What do you think about?:

• basic description of what jwbf is and what it does

• existing code example

• TOC

• information an experienced dev could quickly get started with (repositories, docs, project homepage) so they don't have to scroll past
• separation by language: a Java dev is not going to be interested in Scala sample code
  • < remove the scala parts (a scala dev knows how to transform java2scala)?
• from there, go down the list of steps an inexperienced dev would take: start a project, include dependencies, and get started with sample code

  • here a link to the top and an other example in java how to query e.g. backlinks?

• other resources at the end

[fhocutt]

I think I've addressed all comments--how does it look now?

[eldur]

Fine. I'll squash merge your 3 changes to one (like gerrit code review) and trim the trailing whitespaces. I'll use this squashed commit message. ok?

New "getting started" and reorganization of README.md           

~ Reorganized to put important information at the top           
+ Added more information about dependencies and repositories    
+ Added a "getting started" section with information on Maven   
~ Revised initial "about jwbf"-type statement with more detail  
    and reason to use jwbf                                      
- Removed design goals; these will be added to developerDocs    
~ Clarifications in Getting started and Dependencies            
+ Added table of contents with internal links                   
- Removed Scala section (may add it to developerDoc.md)         
~ Miscellaneous rewording, typo fixes, etc.                     
~ Simplified some wording                                       
~ Readability tweaks                                           

[fhocutt]

Sounds good. Thanks very much!

On Tue, Aug 5, 2014 at 12:21 PM, Loki notifications@github.com wrote:

Fine. I'll squash merge your 3 changes to one (like gerrit code review)
and trim the trailing whitespaces. I'll use this squashed commit message.
ok?

New "getting started" and reorganization of README.md

~ Reorganized to put important information at the top

• Added more information about dependencies and repositories
• Added a "getting started" section with information on Maven
  ~ Revised initial "about jwbf"-type statement with more detail
  and reason to use jwbf
• Removed design goals; these will be added to developerDocs
  ~ Clarifications in Getting started and Dependencies
• Added table of contents with internal links
• Removed Scala section (may add it to developerDoc.md)
  ~ Miscellaneous rewording, typo fixes, etc.
  ~ Simplified some wording
  ~ Readability tweaks

—
Reply to this email directly or view it on GitHub
#26 (comment).

[eldur]

merged

[fhocutt]

Thanks!