[HN Gopher] Readme.so - Easy way to create a README
___________________________________________________________________
Readme.so - Easy way to create a README
Author : ahamez
Score : 52 points
Date : 2024-11-16 15:57 UTC (7 hours ago)
(HTM) web link (readme.so)
(TXT) w3m dump (readme.so)
| hiatus wrote:
| What does this tool give you that a regular markdown editor (like
| the one available at GitHub ) doesn't? Suggested sections? It
| seems like just another markdown editor to me but I'm probably
| missing something.
| ericyd wrote:
| I got the same impression. I think a bullet list reminder if
| useful Readme sections would be just as useful
| alsetmusic wrote:
| I glanced and I don't see anything you don't. Just give me a
| list of suggested headings and a plaintext editor. All this
| does (as far as I can tell) is save you from typing the
| headings yourself. If using markdown, there's some additional
| formatting being applied (which I'm not saying isn't handy),
| but really, who needs a website to do this?
| tptacek wrote:
| It's a markdown editor with templates for common Github README
| pages. That's useful, even if it isn't (so far) technically all
| that complicated. I poked around it and feel like I would
| probably end up with a better README using this than if I just
| threw it together in Emacs. That's interesting.
| jcelerier wrote:
| As someone french the website translation which I assume
| automated is very off-putting - what works well in english ("our
| simple editor") feels to me very strange and icky for a product
| in my mother tongue ("notre simple editeur" / "votre projet").
| I'd have translated it as "Un editeur simple pour rapidement
| ajouter et personnaliser toutes les sections d'un fichier README"
| without involving directly the business and the end-user but
| rather keeping things impersonal.
| Neywiny wrote:
| I used to try do hard with READMEs. Nowadays on my internal
| tooling I put a few helpful commands, screenshots (my goodness
| the amount of programs on GitHub without a screenshot of what it
| does or how it looks), and some info on file formats. I've found
| that gets me most of the way with minimal effort, vs a very well
| formatted, nicely laid out, etc etc which takes so long I run out
| of time for the crucial stuff. Maybe it'd be different if not
| every user was a 3 minute walk from me.
| teddyh wrote:
| Here are the _traditional_ best practices of how README files
| should look:
|
| "The distribution should contain a file named README with a
| general overview of the package:
|
| * the name of the package;
|
| * the version number of the package, or refer to where in the
| package the version can be found;
|
| * a general description of what the package does;
|
| * a reference to the file INSTALL, which should in turn contain
| an explanation of the installation procedure;
|
| * a brief explanation of any unusual top-level directories or
| files, or other hints for readers to find their way around the
| source;
|
| * a reference to the file which contains the copying conditions.
| The GNU GPL, if used, should be in a file called COPYING. If the
| GNU LGPL is used, it should be in a file called COPYING.LESSER."
|
| -- GNU Coding Standards,
| <https://www.gnu.org/prep/standards/html_node/Releases.html#i...>
| (May 26, 2024)
|
| "Good things to have in the README include:
|
| 1. A brief description of the project.
|
| 2. A pointer to the project website (if it has one)
|
| 3. Notes on the developer's build environment and potential
| portability problems.
|
| 4. A roadmap describing important files and subdirectories.
|
| 5. Either build/installation instructions or a pointer to a file
| containing same (usually INSTALL).
|
| 6. Either a maintainers/credits list or a pointer to a file
| containing same (usually CREDITS).
|
| 7. Either recent project news or a pointer to a file containing
| same (usually NEWS)."
|
| -- Software Release Practice HOWTO,
| <https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...>
| (Revision 4.1)
|
| (Repost of <https://news.ycombinator.com/item?id=36776684>)
| __mharrison__ wrote:
| I've found that the easiest way is to use AI to generate the
| README.
| FergusArgyll wrote:
| ofc you'll get downvoted bec "AI"!!
|
| But yes, just dump the code into gemini and ask for a github
| flavored readme and you're 90% there
| stogot wrote:
| Echo "read this" > readme.md
| smusamashah wrote:
| How is this "easiest"? Could have only been a template of readme
| where you could fill whatever fits your need.
|
| This is more like a UI around a template.
| JTyQZSnP3cQGa8B wrote:
| I don't understand either why you would need a whole web site
| to remember "Readme, Usage, Setup, Credits, Release notes,
| etc."
|
| Feel free to write whatever you want. People forgot (or they
| are too young) that old READ.ME files were literally free form
| (with ASCII logos and stuff) and didn't bother with such
| details.
| 1317 wrote:
| i make these headings and write down the answers:
| what is it how do i install it how do i use it
| any "pro-tips"/useful stuff to know how do i get help
| (optional) acknowledgements etc (optional)
|
| too often i see things skip the "what is it" part
| emilamlom wrote:
| I would also say in the "what is it" part that projects
| intended for a broad audience should avoid jargon as much as
| possible. It's frustrating in my experience to have to google
| several acronyms before I can even tell what the purpose is.
| (Security projects/programs are notorious for using way too
| many acronyms for example)
| j1elo wrote:
| My rule for writing documentation is as follows: first use of
| a commonly abbreviated term is written in its complete form,
| with the acronym or short form in parentheses. Then, the rest
| of the text in that same page can freely use the shorter form
| as needed.
|
| So "the File Transfer Protocol (FTP) is bla bla... When using
| FTP, remember to bla bla..."
|
| I think that's the most structured and correct way to
| introduce an acronym. Another style is to use "short form
| (long)" but "long form (short)" feels better to me (although
| I'm not a native speaker so maybe I got it the other way
| around!).
| kstrauser wrote:
| Your method is the most common I've seen. I also come
| across this style often:
|
| > ...using the File Transfer Protocol, or FTP.
| tregoning wrote:
| It would be nice if the app would allow us to save templates
| (no need to get fancy just via URL params e.g. for the above it
| would be something like:`?sections=title&Desc,installation,runL
| ocally,Support,Authors,Ack,usageExamples`
|
| That way we could just generate a 'template' that we can
| share/save etc
| lost_my_pwd wrote:
| A few more more, depending on the nature of the project and
| one's goals: how do I report bugs how do
| I build from source how can I help/contribute
| nicce wrote:
| API Reference as an example is a bit odd. Shouldn't this be auto-
| generated or be part of the docs in the code?
| yardshop wrote:
| It would be a great way to show a few calls as an example of
| the API, then have a link to the auto-generated doc.
| dang wrote:
| Related:
|
| _Readme.so - Easiest Way to Create a Readme_ -
| https://news.ycombinator.com/item?id=27006740 - May 2021 (64
| comments)
|
| _Readme.so - Easiest Way to Create a Readme_ -
| https://news.ycombinator.com/item?id=26919495 - April 2021 (2
| comments)
| netcraft wrote:
| OT: I'm looking forward to an AI tool that can look at an entire
| project and produce documentation for it. Then look at PRs,
| stories, and other project documents and understand how the
| project is changing and keep the documentation up to date.
| netsharc wrote:
| It'd be funny/awesome if the AI can find usage scenarios not
| thought of by the developer. E.g. period trackers ending up
| being a tool for prosecution of women in misogynistic
| regimes...
| yardshop wrote:
| I would call it "an easy way to create a very full featured
| README" because it's not easier than just loading a snippet or
| template in ones text editor, but it does offer a very easy way
| to add specific sections and to customize them.
|
| The "Get Started" button goes right to the editor with three
| panes: list of sections to include, plain text editor for the
| current section, and rendered preview. There's no sign up, and
| the results can be downloaded directly. Very nicely done little
| app.
|
| I felt the default sections were missing something, so I easily
| created this: ## Dad Jokes - Q: did you
| hear about the two antennae who met on a roof top and fell in
| love? - A: well the wedding was okay, but the reception
| was Great!
|
| There, perfect!
| sdesol wrote:
| Once you have created your README, you might want to consider
| using a tool that I'm currently working on. I'm focused on fixing
| the "garbage in, garbage out" problem for RAG by focusing on
| spelling and grammar, among other things. You can see an example
| of the tool in action at
|
| https://app.gitsense.com/microsoft/TinyTroupe?doc=9bc6270618
|
| This will be open sourced and I hope to have source available
| before the end of this month.
___________________________________________________________________
(page generated 2024-11-16 23:01 UTC)