Because, um, you failed to tell us what it even IS? Writing a Great README Don’t be That Guy who clearly works really really hard creating an open source project, puts it up on GitHub with no README whatsoever… and then sits there wondering why nobody is forking their project. Until you’ve written about your software, you have no idea what you’ll be coding. Writing a Readme is absolutely essential to writing good software. I know, I know, we’re programmers, dammit, not tech writers! But that’s where you’re wrong. As in, before you write any code or tests or behaviors or stories or ANYTHING. How bad? Well, Tom Preston-Werner, one of the founders of GitHub, wrote a compelling essay about README Driven Development: “The Readme should be the single most important document in your codebase writing it first is the proper thing to do…įirst. In fact, it’s really bad to skimp on your README. This is understandable software development is a fast-flowing river, and it’s super hard to paddle back upstream to revisit any code that is not a problem/bug/actively on fire. We’ve all done it, every one of us with the intent to come back later and do it right. Too many developers, however, either skip the README entirely, or put some generic boilerplate text in. It’s the first way most people who come to your repo will interface with your project, and it’s so important that GitHub includes README creation prompts in the repository setup workflow: The README is like the public face of your work. Directly below the list of project files is where you find the README. What is a README.md, exactly, in GitHub land? When you visit any repository on GitHub, the first thing you see is the file tree - which, for massive open source projects like the Linux kernel, can be dozens of lines long. This is the closest I’ve gotten to something that looks good in both markdown and preview modes.Hail, fellow Git pilgrims! As we wind down our tutorial series on learning Git and GitHub from your first git init to your most recent pull request, we now pause to consider the humble, often overlooked, README.md file. Then I realized that a tab character in Obsidian will be translated as a valid empty character. on the final line (which displays a single dot). Eventually, it needs to force a full paragraph break by seeing a normal character (a space won’t work). What this is doing is using the “line break” feature of Obsidian’s MD parser to add in line breaks. This is at least somewhat clean looking inside both the straight text version and the preview version. Then, with the very last one I add a single tab key. So I solved it by using a bunch of \ characters, one per line, in multiple lines. Adding a bunch of 's for instance is not my definition of pretty white space when you look at the markdown version. I have a default metadata section that is added at the end of every note, and I greatly prefer to have this stuff pushed down away from the main text of the note.Īlso, there are many ways to add whitespace that look fine in the preview mode, but look rather messy in the edit (markdown) mode. First though - I too would emphasize the desire for adding whitespace with just carriage returns. Just in case you are still looking for a solution, here is the best approach I have.
0 Comments
Leave a Reply. |