Jonathan Corbet <corbet@xxxxxxx> writes: > Anna-Maria Behnsen <anna-maria@xxxxxxxxxxxxx> writes: >> 4. Add a warning banner at the existing documentation and prepare >> everything to get the timer documentation to the proper place and >> create a place for timer documentation below the current structure. >> >> The benefit of 4. for me is, that there is this warning banner at the >> top. So this suggests the reader, that this has to be revisited before >> relying on it for 100%. This banner might also remind the original >> author/technically deep involved developer that this should be >> updated. > > The best thing, of course, is to just fix all of the documentation and > make it perfect now :) > > Failing that, the banners are fine IMO. They mark possibly obsolete > docs, warning readers, and also just might, in an optimal world, inspire > somebody else to work to improve the situation. I hope the world is optimal at least sometimes :) > I've thought for a while that we should have a standard warning or two > along these lines, like Wikipedia does, but of course haven't done > anything about it. > Sure, if we could standardize it, I would definitely prefere it! For me as a not sphinx/rst/... expert, it would be great if only something like .. might_be_outdated:: <optional additional text> needs to be added to the code. And then the default lines would appear together with the optional additional text. Is this what you have been thinking about? Thanks, Anna-Maria
