5 ms·

How do you start documenting software that you don't know well? That seems like a very good way for bad documentation to get out, damaging the project. Perhap

How do you start documenting software that you don't know well? That seems like a very good way for bad documentation to get out, damaging the project. Perhaps this is my impostor syndrome talking, but I for one would be hesitant to tempt the wrath of the Great Unseen Masters that make open source software with potentially inane questions.

ghuntley 10y ago
Overtime, common repetitive questions will surface in conversation. Identify these patterns, write up FAQ/documentation and submit them via the pull-request process. The Great Unseen Masters will typically be grateful and respond with dumping their brain or corrections as they would normally do so in a code review. Eventually, over time, this will build up into something they can point newbies towards to RTFM so the community does not burn out answering the same questions over and over.
- ashitlerferad 10y ago
  If there is a FAQ it probably points to something that needs to be fixed or streamlined.
- muraiki 10y ago
  I think the idea is that FAQ/documentation is normally easily accessible from the repo's page, but not necessarily as obvious to find inside of gitter. I have to confess to having read all your responses but still find your linking to gitter instead of the actual repos to be bizarre.
mastazi 10y ago
I have to say I agree. My only question in the chat would be "where do I find the documentation outside of this chat?"
MaulingMonkey 10y ago
> That seems like a very good way for bad documentation to get out, damaging the project. Read the code, try your best to understand it, and then get the documentation reviewed by someone who does know the software well. This works for code, too. Bonus points: Explicitly enlist feedback ("Anything I'm missing here? Any edge cases I forgot to note? Is my understanding of this correct?") > I for one would be hesitant to tempt the wrath of the Great Unseen Masters that make open source software with potentially inane questions. http://www.catb.org/esr/faqs/smart-questions.html http://www.catb.org/esr/faqs/smart-questions.html But if you're making an effort to contribute, that already counts for a lot. There might be some gruff redirection towards more effective means of contributing, if you're being a significant time sink and not helping that much, but hopefully that's a win/win in the end.

ghuntley 10y ago

Overtime, common repetitive questions will surface in conversation. Identify these patterns, write up FAQ/documentation and submit them via the pull-request process. The Great Unseen Masters will typically be grateful and respond with dumping their brain or corrections as they would normally do so in a code review. Eventually, over time, this will build up into something they can point newbies towards to RTFM so the community does not burn out answering the same questions over and over.

ashitlerferad 10y ago
If there is a FAQ it probably points to something that needs to be fixed or streamlined.
muraiki 10y ago
I think the idea is that FAQ/documentation is normally easily accessible from the repo's page, but not necessarily as obvious to find inside of gitter. I have to confess to having read all your responses but still find your linking to gitter instead of the actual repos to be bizarre.

mastazi 10y ago

I have to say I agree. My only question in the chat would be "where do I find the documentation outside of this chat?"

MaulingMonkey 10y ago

> That seems like a very good way for bad documentation to get out, damaging the project. Read the code, try your best to understand it, and then get the documentation reviewed by someone who does know the software well. This works for code, too. Bonus points: Explicitly enlist feedback ("Anything I'm missing here? Any edge cases I forgot to note? Is my understanding of this correct?") > I for one would be hesitant to tempt the wrath of the Great Unseen Masters that make open source software with potentially inane questions. http://www.catb.org/esr/faqs/smart-questions.html http://www.catb.org/esr/faqs/smart-questions.html But if you're making an effort to contribute, that already counts for a lot. There might be some gruff redirection towards more effective means of contributing, if you're being a significant time sink and not helping that much, but hopefully that's a win/win in the end.