Add a "known issues" chapter to the documentation

Mike Bayer repo owner

changed milestone to blue sky
changed status to wontfix

A "known issues" section which is strictly to document "known" bugs in SQLA is inappropriate since we already have a bug tracking system which handles this use case more effectively and timely than a hardwired documentation section could provide. Bugs change way too quickly for their descriptions to be part of the standard documentation.

OTOH, a section labeled "troubleshooting" strikes me more as one of those useless sections you get on the back page of your new cordless phone instruction manual, and typically include brain dead use cases like plugging the thing in and if the green light doesn't come on, to send it back to the factory. I don't think a simplistic title like that is really capable of delivering on its promise. I don't know what would be in such a section with regards to an open source library.

The other categories of "how do I deal with issue XXX:" which exist are:

DBAPI/database specific limitations. If you have an issue like this, you're definitely going to find DatabaseNotes and you're also going to read the reference documentation for that DBAPI, which has been coming together nicely as in /docs/05/reference/dialects/oracle.html.
Common misunderstandings of the API and it's behavior. For this we have the FAQ. Its in the menubar of the website, its linked all over the place. FAQ is the most appropriate title for this kind of thing, we can add more links to DatabaseNotes and reference documentation there.
"What does this error message mean ?" - this is the one kind of section I've been considering adding, which is a mapping of exception messages (identifier numbers?) ->what does this mean paragraph. This is kind likely an extension of the FAQ. the FAQ is already serving this purpose to some degree as there are exception-specific entries there.

In general "known issues" change incredibly quickly and are not appropriate within the core documentation, and in many cases not even within the FAQ as they are better suited within the bug tracking system where they are already present.

As always feel free to reopen this ticket with more specific verbiage and patches, otherwise I'm trying to keep the size of the open ticketbase under control.

2008-12-25T14:04:47+00:00

Comments (5)

Mike Bayer repo owner
- changed status to wontfix
the documentation contains a link to the wikipage DatabaseNotes. Each dialect should also have a section of notes in the module-level docstrings. While this is not the case for most dialects, Oracle does have this (in 0.5). If you're just starting with SQLA you should be using 0.5.
- 2008-11-24T15:25:34+00:00
Former user Account Deleted
- removed status
- changed status to open
You should have written, what you just wrote, in a "known issues" section in the documentation.

This section is the first place, people are looking for, when they encounter problems that they can't explain. This, and not DatabaseNotes... I'm recommending of writing such page, even if it's all going to be links to other wiki pages.
- 2008-11-24T16:19:59+00:00
Former user Account Deleted
You can also call it Troubleshooting, if you prefer
- 2008-11-24T16:20:34+00:00
Mike Bayer repo owner
- assigned issue to
- changed component to documentation
- changed milestone to 0.5.xx
OK, looking forward to your suggested patch.
- 2008-11-24T16:42:11+00:00
Mike Bayer repo owner
- changed milestone to blue sky
- changed status to wontfix
A "known issues" section which is strictly to document "known" bugs in SQLA is inappropriate since we already have a bug tracking system which handles this use case more effectively and timely than a hardwired documentation section could provide. Bugs change way too quickly for their descriptions to be part of the standard documentation.

OTOH, a section labeled "troubleshooting" strikes me more as one of those useless sections you get on the back page of your new cordless phone instruction manual, and typically include brain dead use cases like plugging the thing in and if the green light doesn't come on, to send it back to the factory. I don't think a simplistic title like that is really capable of delivering on its promise. I don't know what would be in such a section with regards to an open source library.

The other categories of "how do I deal with issue XXX:" which exist are:
- DBAPI/database specific limitations. If you have an issue like this, you're definitely going to find DatabaseNotes and you're also going to read the reference documentation for that DBAPI, which has been coming together nicely as in /docs/05/reference/dialects/oracle.html.
- Common misunderstandings of the API and it's behavior. For this we have the FAQ. Its in the menubar of the website, its linked all over the place. FAQ is the most appropriate title for this kind of thing, we can add more links to DatabaseNotes and reference documentation there.
- "What does this error message mean ?" - this is the one kind of section I've been considering adding, which is a mapping of exception messages (identifier numbers?) ->what does this mean paragraph. This is kind likely an extension of the FAQ. the FAQ is already serving this purpose to some degree as there are exception-specific entries there.
In general "known issues" change incredibly quickly and are not appropriate within the core documentation, and in many cases not even within the FAQ as they are better suited within the bug tracking system where they are already present.

As always feel free to reopen this ticket with more specific verbiage and patches, otherwise I'm trying to keep the size of the open ticketbase under control.
- 2008-12-25T14:04:47+00:00
Log in to comment