51–60 of 75 posts
Judge documentation by its quality of content, not its publishing platform.
> If your documentation is a directory full of files on GitHub, I close the tab. I don't get this at all. Why is a static site (where it's unclear which branch it was generated from or when) better than a bunch of nicely-rendered markdown files stored in a directory?
I'll take a Markdown or plain-text README over a slick set of web pages if the former is current and thorough. Heck, I'd settle for either of those.
Not reading Github pages is stupid and ignorant. You can use Github as a publishing platform. It CAN be good enough for documentation for a small or medium sized project. This can allow quick creation of fairly nice docs, allowing the coder to get back to coding. Hell, all the kernel docs are text files. You gonna tell me you'll never read them on principle? Judge documentation by its quality of content, not its publ…
He's not arguing against GitHub pages - he's arguing against just linking to a file/folder in your GitHub repository and thinking you're done (e.g. //docs" rel="nofollow">https://github.com///docs).
Is it on a wiki? Leave project and never come back.
It's hard to take documentation advice from a blog with a low-contrast text. If I have to struggle a little to read your text, it's clear you're more interested in looking cool than conveying information - a sin as bad as any in the article's list. Not everyone speaks English? Yes, well, not everyone has an excellent screen that brings out the colours you've selected just so.
Screenshot: http://i.imgur.com/qUWjWzb.png
[1] `'goudy old style','minion pro','bell mt'` etc
Next time you come across a project documented solely in Lithuanian / Japanese / Swahili, I hope you will refer to http://ericholscher.com/blog/2014/feb/27/how-i-judge-documen... for insight. English is the de-facto language of the Internet (let's not discuss here how damaging that is to English as a language in general). I strongly believe that public-facing software projects should be documented in English first an…
I'm a consultant in Quebec and I've seen too many companies document code in French. Sometimes variable and function names are in a mix of French and English. The worse is when your errors and exceptions are in French: you get very confused international clients. English reading and writing skills are a MUST for programmers and I envy your working in what sounds like a much nicer code base.
Next time you come across a project documented solely in Lithuanian / Japanese / Swahili, I hope you will refer to http://ericholscher.com/blog/2014/feb/27/how-i-judge-documen... for insight. English is the de-facto language of the Internet (let's not discuss here how damaging that is to English as a language in general). I strongly believe that public-facing software projects should be documented in English first an…
I have to say that I completely disagree with this perspective. Yes, currently our 'lingua franca' of business and technology is English, but I feel that is a problem, not a solution. It's a problem because it unfairly advantages native English speaking people in business. It creates a barrier of entry to people who did not learn English from an early age, along with their native language. It makes it much harder for…
English is currently the best language for software and computer engineering.
So, no, sorry, learn English. Once upon a time to do physics and chemistry you needed German--so, it could be worse.
(And if you didn't win the lottery and start with that language: that sucks, but you'll be that much more valuable if you can act at a translator.)
Earlier quoted context omitted.
Specifying the language with an /en/ in the URL isn't a major inconvenience, and allows for future expansion at the cost of 3 additional characters in an URL. Including it says "I planned ahead and worked intentionally", which shows you care, which fundamentally is what this article is driving at. And yes, documentation should generally be in English first - it's the current language of science and tech, just as it w…
Adding an /en/ when you decide to translate the documentation isn't a major inconvenience either. I would rather add it when it's relevant than include something that will probably never be anything but noise. This is pretty much the same reason I don't put in a bunch of non-functioning UI controls that will hopefully have features attached in the future — my interface is meant to be practical, not aspirational.
Earlier quoted context omitted.
Sure, keep the files as plain text in the repo, I'm all for that. Just don't make it the main interface for viewing them. You are really arguing that a GitHub file browser is the best UX for viewing documentation? Sure, keep documentation about code in the source code. Where exactly in the source code does your tutorial go? You seem to be reading into a lot of things that aren't in the article based on what you want…
less(1) vi(1) emacs(1) firefox(1) google-chrome(1) Microsoft Word or Internet Explorer, if that's your thing! As for "where does your tutorial go," see for example "Control.Pipes.Tutorial". http://hackage.haskell.org/package/pipes-4.0.0/docs/Pipes-Tu... If someone can't figure these things out, by all means, go use someone else's library. This sort of documentation would not be acceptable for a consumer product like…
What's better, the docs for Backbone.Marionette[0], or Backbone[1]?
[0]: https://github.com/marionettejs/backbone.marionette/tree/mas... [1]: http://backbonejs.org/
It's hard to take documentation advice from a blog with a low-contrast text. If I have to struggle a little to read your text, it's clear you're more interested in looking cool than conveying information - a sin as bad as any in the article's list. Not everyone speaks English? Yes, well, not everyone has an excellent screen that brings out the colours you've selected just so.
Not to mention whatever web font that is [1] renders terribly in windows. If I cannot read your article on criticizing text communication without copying and pasting the contents into a text editor, I close the tab. Screenshot: http://i.imgur.com/qUWjWzb.png [1] `'goudy old style','minion pro','bell mt'` etc
