search

mackyle / topgit

TopGit - A different patch queue manager
https://repo.or.cz/topgit/pro.git
Other
67 stars 7 forks source link

README: Split up SYNOPSIS into smaller code blocks #15

Closed cben closed 3 years ago

cben commented 5 years ago

This is cosmetic but IMHO looks better on GitHub: https://github.com/cben/topgit/tree/cben-patch-1/#synopsis

On first reading I was scrolling to find a high-level overview/tutorial "what this does and how does one use this", skipped past the huge code block in SYNOPSIS section and then was a bit lost in CONVENTIONS, NO UNDO caveats etc. and it took me time to realize I must go back and read SYNOPSIS. This is an attempt to make it less "scary wall of code" and more welcoming "small examples" for impatient readers like me :wink:

(At first I tried just turning on shell highlighting for comments and prompts to stand out, but it felt too weak, it's not even highlighting prompts/commands vs output: https://github.com/cben/topgit/tree/248246e28fda3934e21b1d7185519088e71e4657/#synopsis Also, dedenting the texts make them stand out better when reading less README in terminal too.)

mackyle commented 4 years ago

I apologize for the delay. Life happens.

When I started working on TopGit, the help was already written in what was basically the ".rst" format with only one or two minor tweaks needed. I intend to overhaul it at some point and likely migrate it to ".md" format.

Additionally, I think it's gotten a bit large for a “README” :)

There’s a better formatted version at https://mackyle.github.io/topgit/topgit.html which may be a bit easier to read.

I would be more interested in what you would expect to see in a succinct, separate readme that would answer your question:

"what this does and how does one use this"

That’s what really belongs in the readme with pointers to the in-depth docs if someone is further interested.

I’m not sure there’s a short and sweet answer to the ”how does one use this” part as that’s like asking “how does one use Git?”

mackyle commented 3 years ago

The topgit-0.19.13 release has moved the README to README_DOCS.rst and added a new README that hopefully provides a much simpler and useful overview of what TopGit does.