Skip to main content
replaced http://meta.stackexchange.com/ with https://meta.stackexchange.com/
Source Link

One problem touched on in a couple of other answers is that documentation needs to evolve with the language, library or tool it's documenting. Apparently obsolete answersobsolete answers are a pretty big problem here, and so would likely be a problem with documentation as well. One particular problem with dealing with obsolete answers, is while they may deal with older versions, many people may still be using the older version making the answer still useful.

I think that means that the new documentation feature is going to need to handle multiple versions of a topic explicitly. There can't be just be one version the Python topic for urllib, there needs to be at least one for each of Python 2.7 and Python 3.x. And no, just going with 3.x isn't really a good option, given that the 2.7 tag is more popular than the 3.x tag. On the other hand there are probably enough Python topics that would be same in all versions that completely partitioning Python documentation by version wouldn't be a good idea.

One advantage of having topics tied to specific versions (and not moving targets like Python or Python 3.x) is that they won't rot on the vine. Obsolescence becomes much less of a problem this way.

More generally I'm worried about the overall quality the documentation, I don't think there's necessarily the right expertise here to create better documentation than the web already offers.

One problem touched on in a couple of other answers is that documentation needs to evolve with the language, library or tool it's documenting. Apparently obsolete answers are a pretty big problem here, and so would likely be a problem with documentation as well. One particular problem with dealing with obsolete answers, is while they may deal with older versions, many people may still be using the older version making the answer still useful.

I think that means that the new documentation feature is going to need to handle multiple versions of a topic explicitly. There can't be just be one version the Python topic for urllib, there needs to be at least one for each of Python 2.7 and Python 3.x. And no, just going with 3.x isn't really a good option, given that the 2.7 tag is more popular than the 3.x tag. On the other hand there are probably enough Python topics that would be same in all versions that completely partitioning Python documentation by version wouldn't be a good idea.

One advantage of having topics tied to specific versions (and not moving targets like Python or Python 3.x) is that they won't rot on the vine. Obsolescence becomes much less of a problem this way.

More generally I'm worried about the overall quality the documentation, I don't think there's necessarily the right expertise here to create better documentation than the web already offers.

One problem touched on in a couple of other answers is that documentation needs to evolve with the language, library or tool it's documenting. Apparently obsolete answers are a pretty big problem here, and so would likely be a problem with documentation as well. One particular problem with dealing with obsolete answers, is while they may deal with older versions, many people may still be using the older version making the answer still useful.

I think that means that the new documentation feature is going to need to handle multiple versions of a topic explicitly. There can't be just be one version the Python topic for urllib, there needs to be at least one for each of Python 2.7 and Python 3.x. And no, just going with 3.x isn't really a good option, given that the 2.7 tag is more popular than the 3.x tag. On the other hand there are probably enough Python topics that would be same in all versions that completely partitioning Python documentation by version wouldn't be a good idea.

One advantage of having topics tied to specific versions (and not moving targets like Python or Python 3.x) is that they won't rot on the vine. Obsolescence becomes much less of a problem this way.

More generally I'm worried about the overall quality the documentation, I don't think there's necessarily the right expertise here to create better documentation than the web already offers.

Source Link
Ross Ridge
  • 40k
  • 1
  • 14
  • 11

One problem touched on in a couple of other answers is that documentation needs to evolve with the language, library or tool it's documenting. Apparently obsolete answers are a pretty big problem here, and so would likely be a problem with documentation as well. One particular problem with dealing with obsolete answers, is while they may deal with older versions, many people may still be using the older version making the answer still useful.

I think that means that the new documentation feature is going to need to handle multiple versions of a topic explicitly. There can't be just be one version the Python topic for urllib, there needs to be at least one for each of Python 2.7 and Python 3.x. And no, just going with 3.x isn't really a good option, given that the 2.7 tag is more popular than the 3.x tag. On the other hand there are probably enough Python topics that would be same in all versions that completely partitioning Python documentation by version wouldn't be a good idea.

One advantage of having topics tied to specific versions (and not moving targets like Python or Python 3.x) is that they won't rot on the vine. Obsolescence becomes much less of a problem this way.

More generally I'm worried about the overall quality the documentation, I don't think there's necessarily the right expertise here to create better documentation than the web already offers.