Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write the Docs

docs.writethedocs.org

Post reply on HN
Print view View original

21–23 of 23 posts

Re: Write the Docs

#21

Post by roryokane »

vog wrote: post #20

I'm not sure it it's a good idea to start with a word play: > Well, you’ve come to the write [sic] place. I believe that most readers of that site will be non-native speakers, who may or may not get such in-language jokes. Also, what I'm missing most is not how to structure text, but a concise(!) overview of the most important grammar rules, i.e. stuff that can't be easily checked via dict.cc or similar sites. Are th…

I can’t think of any grammar rules that are more applicable to documentation than to other writing. Thus, I think giving an overview of grammar rules would be out-of-scope for this site, and shouldn’t be added. However, it might be in scope for this site to have an appendix with a list of links about writing in general, and such a grammar site would deserve a spot.

> I believe that most readers of that site will be non-native speakers

I don’t see why this site would get a higher proportion of non-native speakers than any other site. Learning to understand a language and learning to write well in it are mostly separate things, and I think native speakers will understand that, so they won’t avoid using this site just because it’s about writing in English. Or are you saying that there are more non-native-speaker users in general who browse English programming sites than native-speaker users?

Re: Write the Docs

#22

Post by krick »

vog wrote: post #20

I'm not sure it it's a good idea to start with a word play: > Well, you’ve come to the write [sic] place. I believe that most readers of that site will be non-native speakers, who may or may not get such in-language jokes. Also, what I'm missing most is not how to structure text, but a concise(!) overview of the most important grammar rules, i.e. stuff that can't be easily checked via dict.cc or similar sites. Are th…

> I believe that most readers of that site will be non-native speakers, who may or may not get such in-language jokes.

Doesn't look like a big problem to me. I'm non-native speaker myself and I got the joke just fine, even though I didn't find it very amusing. And even if I wouldn't, I'd just skip that sentence without worrying too much about it (probably thinking it means "place for writing" or something like that).

Re: Write the Docs

#23

Post by vog »

krick wrote: post #22
vog wrote: post #20

I'm not sure it it's a good idea to start with a word play: > Well, you’ve come to the write [sic] place. I believe that most readers of that site will be non-native speakers, who may or may not get such in-language jokes. Also, what I'm missing most is not how to structure text, but a concise(!) overview of the most important grammar rules, i.e. stuff that can't be easily checked via dict.cc or similar sites. Are th…

> I believe that most readers of that site will be non-native speakers, who may or may not get such in-language jokes. Doesn't look like a big problem to me. I'm non-native speaker myself and I got the joke just fine, even though I didn't find it very amusing. And even if I wouldn't, I'd just skip that sentence without worrying too much about it (probably thinking it means "place for writing" or something like that).

Don't get me wrong. I'm not a native English speaker, either. And I got that joke, too. However, it still felt out of place there.
Post reply on HN