Let's say I'm working on a class or a library for a specific framework, and I'm working on writing its documentation.

Where is the best place to ask a question about that? For example: "is this the best way to explain this" or "should my docs be too noob friendly or too technical" or "is there a specific format that documentations usually use"?

I don't think StackOverflow is the right place? Programmers.SE?

EDIT: I wasn't really sure how to ask it, but I just want to know if my docs are understandable or not? If they are confusing or not? That's what I really want to ask.

share|improve this question
    
Thanks @Yannis, didn't realize there was a site-rec tag. –  Rocket Hazmat Dec 12 '12 at 19:28
1  
Sounds very subjective for SO. If you try it, be really sure to make it as objective as possible. Depending on the exact question might be better for Programmers indeed. –  Mat Dec 12 '12 at 19:29
    
@Mat: I'm not very good at writing docs, so I'd want to make sure people using my class understood it without having to ask me. –  Rocket Hazmat Dec 12 '12 at 19:30
1  
That's a universal problem, nothing really specific to programming at all. (I'm not very good at explaining myself either.) Different people do things differently, standard vary widely between platforms/languages/companies/continents. Your sample questions 1 and 2 are IMO not appropriate for SO or Programmers. N°3 I'm not sure. –  Mat Dec 12 '12 at 19:32
    
@Mat: I guess I could just read other people's docs and try to copy their format :-P –  Rocket Hazmat Dec 12 '12 at 19:34
2  
Re. your edit: your need something like docreview.stackexchange.com which doesn't exist. I don't see any existing site where that would fit. –  Mat Dec 12 '12 at 19:45
    
@Mat: Maybe someone should suggest it on Area 51 :-P –  Rocket Hazmat Dec 12 '12 at 19:48
    
Hmm, I see you've edited your question with something my answer does not account for. I would agree with @Mat that the particular question is not really a fit for any site. –  Bart Dec 12 '12 at 19:48
    
@Bart: Well, guess my users will have to suffer with bad docs :-P Do you think a Area 51 proposal for this would be a good idea? Because I could start that ^^ –  Rocket Hazmat Dec 12 '12 at 19:52
    
@RocketHazmat You could give it a try. Don't think this will be an easy thing to do though. You can't merely propose something and expect it to take off (which does seem to be the idea of many proposal creators). You'll need to carefully outline the site and its purpose and put in a significant amount of effort to get it anywhere near a beta stage. But give it a go if you think it's of value. I would say it's a difficult topic for a site, but difficult is not necessarily impossible. –  Bart Dec 12 '12 at 19:55
    
@Bart: I understand. But I also believe that there are other developers out there who would like a place to ask about their documentation! –  Rocket Hazmat Dec 12 '12 at 19:56
    
Then by all means try. –  Bart Dec 12 '12 at 19:57
    
@Bart: Let's see what happens: area51.stackexchange.com/proposals/48486/program-documentation –  Rocket Hazmat Dec 12 '12 at 20:00
add comment

3 Answers

up vote 6 down vote accepted

"Please critique my document" isn't a good fit for Stack Exchange, but Writers.SE has a small contingent of technical writers (it's not just for fiction) and critique questions within certain limits are accepted. If you can target your question a little more, you could ask there. Such targeting could go along any of the following dimensions:

  • best ways to present {architecture, high-level design, low-level implementation} info

  • conventions for signatures, class diagrams, workflow diagrams, etc

  • trade-off between experts and newbies: how do I decide what background knowledge to assume, link to, or explain? (and writing for multiple audiences in one doc)

  • presentation of examples: commented code, full-on written tutorial, something in between?

share|improve this answer
    
Writers.SE seems like a good place actually! My area 51 proposal was closed as a duplicate of writers. –  Rocket Hazmat Dec 12 '12 at 21:13
    
Ha, never even heard of it. Excellent suggestion. –  Bart Dec 12 '12 at 21:17
    
FWIW, I wasn't a pro-tem moderator on Writers when I wrote this answer, but I am now. –  Monica Cellio May 16 '13 at 15:51
add comment

I don't really think any of the questions you propose are a good fit for Stack Overflow. You say;

"is this the best way to explain this"

That is a very subjective question and not something that is likely to survive as a question. Not on Stack Overflow, nor on any other related site within the network that I know of.

"should my docs be too noob friendly or too technical"

Once again, a fairly subjective question, if not a poor question in its own right. Not Stack Overflow material.

"is there a specific format that documentations usually use"?

This comes closest to a decent question, but I don't think Stack Overflow is the place for it. This might get closer to a Programmers SE question, looking at some of the content in their documentation or documentation-generation tags.

I won't outright recommend you to post your questions there (because your one-liner examples are not enough to judge, and your edited example seems to be outright off-topic), but it might be a better bet than Stack Overflow. Carefully look through some of the questions asked, and try to steer away from highly subjective questions. And if you're not sure, propose the question you want to ask (or a clear outline of it) on their Meta or in their main chatroom.

share|improve this answer
    
Yeah, I wasn't really too sure about my examples either. I just wanted to know what site documentation questions would be on topic at. Programmers seems like a good bet, I should be able to write a decent question :-P –  Rocket Hazmat Dec 12 '12 at 19:44
1  
Like I said, should you still not be sure, by all means ask on their Meta. Better safe than sorry. –  Bart Dec 12 '12 at 19:45
2  
@RocketHazmat You could also ask around in the main ProgSE chat room, The Whiteboard. Documentation is certainly on topic, but your example questions don't really help, if you can come up with a bit more concrete example the chat room's regulars can point you to similar questions and guide you through the site's nuances. –  Yannis Dec 12 '12 at 19:56
add comment

I personally think that StackOverflow it the right place. It's a question about programming and its documentation. So I think a question about documentation would fit there.

But you should not forget to write your questions in a generic kind so that your question is helpful for other too.

share|improve this answer
    
I guess. I just wasn't sure if it'd be well received there. –  Rocket Hazmat Dec 12 '12 at 19:29
1  
I'm sorry, I disagree for the first two sample questions. The third might survive on SO depending on language/framework. –  Mat Dec 12 '12 at 19:30
    
@Mat Yeah - I can only see this working on SO if the question was "How do I change the default table of contents using Sphinx with Python" or similar... –  Jon Clements Dec 12 '12 at 19:34
    
Of cause you are right that this can be very subjective, but if you think about such a question you may write it more in a generic way, and this is wanted at SO isn't it? –  rekire Dec 12 '12 at 19:34
    
Generic's not the problem here, but (IMO) objectivity. "Is this the best way to explain this?" is pretty much impossible to frame properly because it is very, very dependent on target audience/culture. "Should my docs be noob or pro" either isn't a question (target audience is known to be one or the other), or completely subjective (and again, dependent on culture/image). –  Mat Dec 12 '12 at 19:39
    
@Mat: I wasn't sure how to ask it, I guess. I just kinda want to know if the docs I wrote are confusing or not. –  Rocket Hazmat Dec 12 '12 at 19:41
1  
@RocketHazmat: that one's easy to answer: if you find them confusing, they are. If you don't find them confusing, someone else will. :) –  Mat Dec 12 '12 at 19:42
    
@Mat: Sounds about right. –  Rocket Hazmat Dec 12 '12 at 19:45
    
Hm it seems that my answer is not really helpful. Should I delete it if I get more downvotes? Btw I think it is very hard to get upvotes that in the last time on meta. –  rekire Dec 12 '12 at 19:45
    
@rekire: Downvotes here just mean people disagree. I upvoted you because I agree, but it seems others don't think the same way. –  Rocket Hazmat Dec 12 '12 at 19:49
1  
@rekire There is no need to delete anything. Nobody can force you to do so. There are just 2 users who seem to disagree with what you've said. That's all. –  Bart Dec 12 '12 at 19:49
add comment

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .