Eric Holscher

> Most developers have high-end salaries, IMO.

David Glick and I are currently the top two on Gittip, and neither of us have high-end salaries right now:

http://blog.gittip.com/post/27072581481/i-believe-in-gittip

http://glicksoftware.com/blog/goodbye-groundwire

#3 is Eric Holscher, and he's specifically using his gittips to host ReadTheDocs.org:

http://ericholscher.com/blog/2012/sep/20/help-fund-read-docs/

#5, Alex Gaynor, has a high-end salary (I'm assuming). So far it sounds like he's planning to use his gittips to attend an extra conference or two this year:

http://news.ycombinator.com/item?id=4438937

#7, Mike Bayer, has also said that his gittips are covering his infrastructure costs, for SQLAlchemy:

http://www.reddit.com/r/Python/comments/10a32v/gittip_is_the_future/c6bvho1

> Gittip also lacks focus, it doesn't commit a developer to work on something, it's merely a thank you, a donation.

Not sure where you're coming from on this. It sounds like you're talking about the focus and drive of someone receiving money on Gittip. The idea is that people worth giving money to on Gittip are people with a history of productive self-motivation, people that don't depend on coercive economic relationships to stay focused.

Honestly, for me, there's nothing more humbling and motiving to get me out of bed in the morning than knowing that 100+ people believe in me enough to freely give me $1+ this week. That keeps me way more focused than a corporate salary ever did.

>…

> I think it's time Markdown should be supported natively by browsers.

I'd rather have AsciiDoc become the default lightweight documentation format. Markdown suffers from competing standards regarding extensibility beyond basic formating, whereas AsciiDoc is a quite direct translation of the solid standard Docbook.

Extending Markdown to anything more complex than bold, italic or headers requires deciding among a number of competing tools with different syntax and installing them as extensions. AsciiDoc has features as tables, references, images or metadata integrated in the standard, and it has been designed for extensibility, while Markdown was not.

There is an advantage of using Markdown over AsciiDoc, which is that it is currently supported by a larger variety of tools. But that advantage is somewhat negated by its different and slightly incompatible flavors.

https://asciidoctor.org/docs/asciidoc-vs-markdown/

https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

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-documentation-quality/#language 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 and foremost, with translations to other languages added as resources allow.

I work for a small company in Quebec (that's the Canadian province that has a Language Police) - despite most of the team being Francophone, all our internal documentation and code docs are in English. Why would that be? Because everyone realizes, without ever really having discussed it, that it is the only efficient way to do it, if we want to collaborate with others, if we want to grow, if we want others to contribute, having everything in French would be creating unnecessary hurdles.

ReST is really big in the Python ecosystem, thanks to Sphinx (docs generator), and the read-the-docs website.

The main advantage for ReST is that it is well defined and consistent. It's a bit heavier than .md, but I think it will pay off for large projects.

Here are some articles about it:
https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/
http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

I've written docs for personal projects in markdown, but now that I work on larger collaborative projects I feel like ReST is the way to go.

PS: If you're using Sphinx, you can actually support both .md and .rst in the same project, and slowly transition from one to the other, see https://github.com/ivanistheone/ricecooker/blob/docs/improve/docs/conf.py#L447

I've always found that documentation is a skill on it's own. You need to learn how to say something efficiently while answering as many questions as you can. If it's too much people won't read it, if it's too little then it's not useful.

Also learn how to ask questions, you know your project inside and out, try to go to someones position of not knowing anything. I always find stuff that seems so simple at first but then later realize that most people wouldn't know it or connect the dots because they don't know the project.

Here are some resources I've looked at.

https://jacobian.org/writing/what-to-write/

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

https://www.braintreepayments.com/blog/api-where-to-begin/

http://warpspire.com/talks/documentation/

I didn't file a bug report because I'm not entirely sure what I would file it as; "Excessive use of magic?".

What happened in my case is that when using multiprocessing with Django, if a database connection is opened by the main process to make a query that connection is kept open and workers end up using it instead of spawning their own. If I manually close the connection, they all make their own. This isn't sufficient, however, because global imports related to transaction support still manage to step on each other when queries are run concurrently. This turns out to be a pretty rare race condition, but it does happen.

You can read more at the comment here, including my workarounds: http://ericholscher.com/blog/2008/nov/10/announcing-django-crawler-test-utils/#c211