Post History
A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically ...
#4: Post edited
by
Monica Cellio
·
2020-07-10T01:03:17Z (over 4 years ago)
A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically showing only the relevant excerpts from the sample code. (Nobody wants to see a 200-line program inline in a book, but it's important to show that 20-line excerpt that demonstrates a principle right there in the section that talks about that principle.)This creates a maintenance challenge: over a progression of releases, interfaces or preferred coding patterns change. An IDE (a code-development environment) provides tools for finding the example programs that need to be updated (e.g. find all places where this function is called), but they don't tend to help with references in documentation. So what usually happens, in my experience, is that before a release somebody will page through the documentation looking for suspicious code snippets. This is, obviously, not 100% reliable. (Edit: the full examples are tested regularly, but that doesn't guarantee that the excerpts in the documentation remain in sync with the full example.)Currently we rely on the technical writers, who we hope remember which examples were excepted in documentation where, to react when the example code or the relevant interfaces change. The team is fluent with the bug-tracking and source-control systems, including subscribing to check-ins, but we are still relying on people's personal knowledge, which becomes a problem if people leave the team. (As is often the case, testing of documentation tends to be a low priority for QA.)I am looking for practices _that have been used successfully_ to improve the ongoing accuracy of code examples in documentation.
- A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically showing only the relevant excerpts from the sample code. (Nobody wants to see a 200-line program inline in a book, but it's important to show that 20-line excerpt that demonstrates a principle right there in the section that talks about that principle.)
- This creates a maintenance challenge: over a progression of releases, interfaces or preferred coding patterns change. An IDE (a code-development environment) provides tools for finding the example programs that need to be updated (e.g. find all places where this function is called), but they don't tend to help with references in documentation. So what usually happens, in my experience, is that before a release somebody will page through the documentation looking for suspicious code snippets. This is, obviously, not 100% reliable. (Edit: the full examples are tested regularly, but that doesn't guarantee that the excerpts in the documentation remain in sync with the full example.)
- Currently we rely on the technical writers, who we hope remember which examples were excepted in documentation where, to react when the example code or the relevant interfaces change. The team is fluent with the bug-tracking and source-control systems, including subscribing to check-ins, but we are still relying on people's personal knowledge, which becomes a problem if people leave the team. (As is often the case, testing of documentation tends to be a low priority for QA.)
- I am looking for practices _that have been used successfully_ to improve the ongoing accuracy of code examples in documentation.
#3: Attribution notice added
by
System
·
2019-12-08T02:14:01Z (about 5 years ago)
Source: https://writers.stackexchange.com/q/5139 License name: CC BY-SA 3.0 License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision
A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically showing only the relevant excerpts from the sample code. (Nobody wants to see a 200-line program inline in a book, but it's important to show that 20-line excerpt that demonstrates a principle right there in the section that talks about that principle.) This creates a maintenance challenge: over a progression of releases, interfaces or preferred coding patterns change. An IDE (a code-development environment) provides tools for finding the example programs that need to be updated (e.g. find all places where this function is called), but they don't tend to help with references in documentation. So what usually happens, in my experience, is that before a release somebody will page through the documentation looking for suspicious code snippets. This is, obviously, not 100% reliable. (Edit: the full examples are tested regularly, but that doesn't guarantee that the excerpts in the documentation remain in sync with the full example.) Currently we rely on the technical writers, who we hope remember which examples were excepted in documentation where, to react when the example code or the relevant interfaces change. The team is fluent with the bug-tracking and source-control systems, including subscribing to check-ins, but we are still relying on people's personal knowledge, which becomes a problem if people leave the team. (As is often the case, testing of documentation tends to be a low priority for QA.) I am looking for practices _that have been used successfully_ to improve the ongoing accuracy of code examples in documentation.
#1: Imported from external source
by
System
·
2012-03-02T03:21:55Z (almost 13 years ago)
Original score: 22