How to judge documentation in 30 seconds.

Source: http://ericholscher.com/blog/2014/feb/27/how-i-judge-documentation-quality/

 

 A Website

If your documentation is a directory full of files on GitHub, I close the tab. With GitHub Pages, Read the Docs, and other places to host generated documentation for free, not making an effort is unforgivable.
If this is your project, please check out Mkdocs. It is still a new tool, but it will give your users something much nicer. I also recommend Sphinx for the most mature approach to documentation.

 

Prose

If your documentation is generated from source code, I am immediately skeptical. You should use words to communicate with your users, and those words shouldn’t live in your source code. If you included all of the things needed to document a project in source, your code would be unreadable.
So please, use a tool that allows you to write prose documentation outside of your source code. Your users will thank you.
A great start is to read this series on Writing Great Documentation, and the resources on the Write the Docs docs. [1]

 

Permalinks

One of the primary uses of documentation is the ability to link information to other people. If your documentation doesn’t have an easy way to link to sections of content on a page, then the value decreases. Your users should never have to send someone a link and say “go here and search for X”. That means your documentation has failed your users.
You’ll notice even my blog has permalinks. I believe all text content should, because it greatly increases the utility of the content.

 

URLs

There are two things I always look for in the URL:

• Language
• Version

Most often, projects don’t have either. Your URL should look something like: https://docs.project.com/en/1.0/

 

Versions

I see versions in lots of documentation, but not nearly enough. If your project has versions, your documentation should too. Not everyone can always upgrade to the latest version. If someone is using an old version, they should have access to documentation for that version.
Along the same lines, you should also have documentation for your development version. If the docs don’t have a version attached, I have no idea if they are up to date or not. You should clearly mark your released versions and development version, otherwise users will get confused.

 

Language

Language is one I rarely see. The software world has a nasty habit of forgetting that the whole world doesn’t speak English. If you don’t provide a language in your URL, you are implicitly sending the message that the documentation will never be translated.
I believe that translating documentation is a really important step towards helping people learn to program. Someone shouldn’t have to learn Programming and English at the same time.
Translations are quite a bit of work, so I understand why many projects don’t have them. But you should at least acknowledge the possibility of translation by putting the language in the URL.

 

Conclusion

That is the 30 second way that I determine if a project’s documentation is worth looking at. These are all hints about if a project actually cares about its docs. If the project doesn’t care about its documentation, that is a good sign that you probably shouldn’t use it.

Bash process subsitution

command >(process list) or command <(process list)

Nifty way of communicating with a process, <(process list) takes output and pumps it into the command, where as command >(process list) provides input to the process from the command.

Source:

http://www.gnu.org/software/bash/manual/html_node/Process-Substitution.html#Process-Substitution

Freedom to fail

Keep finding lots of really good articles on HackerNews..

This paraphrase is from http://antonopoulos.com/2014/03/02/failure-is-an-option/

Recently, the US has been infected by the “failure is not an option” mantra, a toxic hubristic fallacy, disguised as a truism, which promotes the idea that risk can be removed from life; that 100% security and 100% control are possible, even desirable. Those who attempt to remove the possibility of failure, to de-risk financial systems, end up creating the probability of spectacular failure. By removing the option to fail cheap and fail fast, they instead concentrate risk and ensure we will fail hard, fail expensively, fail across the board.

In the 1970s the US developed a policy of forestry that espoused 100% prevention of forest fires; let’s call it “fire is not an option”. This policy resulted in the systemic suppression of small fires and eventually into very unbalanced forest ecosystems where fire is now not just an option, but a certainty of disaster. We now know that fire is a natural part of a forest’s life-cycle. Without fire, the forest floor gets overgrown, making it a source for bigger and hotter fires. When fires break out in a “managed” forest where fires have been suppressed for years, they burn so hot they turn the ground to glass. Fires that were survivable by trees are now so destructive that they denude hills and wipe out the entire ecosystem. Our financial system has become much like a poorly managed forest, harboring within it the increasing probability of a systemic and destructive conflagration.

Capitalism and entrepreneurial innovation require risk, as it is a fundamental component of business evolution. When companies are allowed to fail, their resources get reallocated in the market, just like a fire that converts sparse undergrowth into fertilizer for the next generation of trees. If instead, the failed companies are prevented from failing but are propped up to maintain the illusion of solvency, they fester and consume more and more resources while creating greater and greater risk. Eventually, bail-outs must be followed by even greater bail-outs and then bail-ins. Finally, the systemic risk of too-big-to-fail becomes too-big-to-bail and the economy suffers a conflagration of defaults. De-risking increases the risk of failure and turns localized risk into a systemic risk. If you stop the small fires, you get a fire so big it turns the ground to glass.

30% feed back when 30% done.

Good article on dealing with feedback and how to give and receive it better.

Copied and pasted most interesting section. Source: http://blog.42floors.com/thirty-percent-feedback/

How to Build 30 Percent Feedback into the Culture of Your Startup

Lead by example

Duh.
Don’t worry about anything else below if you can’t there.

Ask for it explicitly

You have to be deliberate because you’re fighting against an innate fear most people have: fear of rejection.   Some of your best people are accustomed to being good at everything they do, so they may be the toughest to get on board.
You have to explicitly ask people to be on board with this concept.

Reward People with great feedback

Whenever someone comes to you for early feedback you have to reward it.  If, even just once, you reject someone’s draft because it’s not polished enough for you, you’ll teach everyone else in the organization to always be 100% done before approaching you.
Execs at big companies may want everything perfect before it gets to them, but that’s no way to run a startup.

Praise Speed

When someone takes way too long to get a first draft out because they’re being perfectionists and you praise them for their quality craftsmanship, it teaches everyone to do the same.  You should, instead, praise people that move incredibly fast.  We always strive for one week.  Even for the most complex projects, we try to see what can come out as a first draft within one week.  From that point on, they can get feedback and start iterating.

Demo Regularly

Set up the company for everyone to demo at your weekly meetings, regardless of what stage their project is in.  It’s more of a show us whatever you have.  PG would do this to us at YC, making us demo every week.  It was both daunting and humbling.  But once we got used to it, we actually got addicted to the immediate feedback.  That’s the culture you want.


One final note.  Every once in awhile you’ll still have to give someone  tough feedback when they thought they were 90% or 100% done.  It always feel shitty to have throw away work.  But hopefully with this system, it will happen much less.  And the result will not only be better products, but happier people.

Software methodologies..

"Once a programming team has adopted a methodology it’s almost inevitable that a few members of the team, or maybe just one bully, will demand strict adherence and turn it into a religion. The resulting passive-aggression kills productivity faster than any methodology or technology decision."

http://typicalprogrammer.com/why-dont-software-development-methodologies-work/

Code Reviews and Bad Habbits

Quoting particular sections:

There are two fundamental problems with single-patch review systems:

1. They encourage lumping at-best-weakly-related changes together. Frequently, when I start implementing a new feature, there are at least three steps: first, refactor the existing code to make it clean to add the new feature; next, add the new feature; and finally, add unit tests. The bigger the feature, the more likely each of these steps is likely to itself consist of several logical steps. If you can store several distinct commits in a single review, then you can simply keep these commits grouped together. But if I’m in a single-patch system, I’m going to be strongly encouraged to do everything in one massive commit. That’s especially frustrating because refactoring existing code, and adding new code, get lumped together, demanding much more mental energy on my part to figure out what’s actually going on in a given review.
   You might argue that you can keep the patches split, creating one review per commit, but that’s actually worse. At best, you’re now separating the tests from the feature, and the refactoring from the motivation for the refactoring. But the real issue is that many single-patch systems make it very easy to approve any one of the commits in isolation, which is exactly the opposite of what you want. Thus, one-review-per-commit switches the balance from “annoying” to “dangerous.” Not really an improvement.
2. They encourage you to hide your history. The whole point of a source control system is to tell you the history of how code got to be the way it was. I want to be able to see what it looked like yesterday, and last February at 2 PM, and anything in between. Sometimes that’s because I know that the code worked then and doesn’t now, and I want to know why, but lots of the time, it’s because I want to know why a given change was done. What was the context? What was the motivation? When you just keep updating one single patch the whole time it’s under review, I’m losing tons of history: all I’ll get is a single finished product as a single patch, without any of the understanding of how it got that way.

http://bitquabit.com/post/code-reviews-and-bad-habits/

Building emacs 24 on Ubuntu 13.10, 14.04, and 15.10

1. sudo apt-get install autoconf texinfo libtiff4-dev libgif-dev libxpm-dev libncurses-dev
2. git clone git://git.savannah.gnu.org/emacs.git
3. cd emacs/
4. ./autogen.sh
5. Not interested in makeinfo at this time, so
• ./configure --without-makeinfo
6. make
7. sudo make install

Updates for 14.04

For step 5, use ./configure --without-makeinfo --with-tiff=no

Updates for 15.10

For step 1, use sudo apt-get install autoconf texinfo libtiff-dev libxpm-dev libncurses-dev libgif-dev libjpeg-dev libgtk2.0-dev