documentation testing¶

To ensure that the project can continue to be maintained, the top priority should be to make it so that other programmers can maintain it, too¹. This would involve:

1. setting aside time and funding for documentation testing
2. finding a documentation tester who would try running the data loading processes and report any issues they encounter
   • the funding would be taken out of the remaining BIEN3 budget²
   • if we do not find someone, I would instead guess at what feedback they might provide. this may leave important steps unexplained, if I guess wrong that someone would understand them.
3. receiving feedback from them
   • the feedback must be in a written, searchable format such as e-mail or IM, so that we can include questions answered with the other documentation as an FAQ
     • non-written/non-searchable recorded formats are discouraged because they make it difficult for the user to find the information they need
     • transcribable formats are also discouraged because they must be transcribed to make the information available and useful, and usually only a portion of what is said ends up transcribed
     • communication should be arranged to maximize the portion that happens via e-mail, so that as much as possible ends up directly in written, searchable format
   • all feedback must be placed under project version control so it's available in the same place as the code and other documentation
4. fixing any issues uncovered, so that the documentation tester is able to fully run the key data loading steps

¹ since no one but me has yet tried to run the data loading scripts, we do not know if someone other than me would be able to successfully run them

² because the iPlant grant did not include database maintenance funding past the development stage (similar to what VegBank has)
.

documentation tester¶

responsibilities¶

• ensure that the instructions I have written are correct and understandable by a programmer other than me:
  • mapping a new datasource, which involves understanding the map spreadsheet format and the terminology in the VegCore data dictionary
  • loading a new datasource, which involves running a set of commands to upload the data to vegbiendev and check it into version control
  • testing the installation from scratch of the DB, to ensure that this process is sufficiently documented so that someone else could run it
• suggest steps that could be automated to facilitate using the database

skills needed¶

• read technical documentation
• run command-line commands
• use a relational database (PostgreSQL preferred)
• ability to code in SQL is ideal, but probably not needed for adding simple datasources (e.g. flat specimens data)

support person¶

In addition, for complex databases like VegBIEN, it is often necessary to have a support person to help users map and load their data. For example, Mike Lee sometimes helps data providers use VegBranch and find the right VegBank column to map their data to.

• the support person would ideally be the same as the documentation tester, so that if they learn how to do the data loading, they will already know how to assist data providers
• this should preferably be someone who is around long-term after the BIEN3 project³ (such as a long-term NCEAS or iPlant employee)
• their funding would also be taken out of the remaining BIEN3 budget, paid at a certain % time. e.g. paying them at 10% like Mike Lee on VegBank would stretch the remaining funds for 10 times as long.

³ so that if any of the training does not end up in a written format, they would be less likely to leave and take the transferred knowledge with them
.

responsibilities¶

• assist users in mapping and loading their data

skills needed¶

• documentation tester's skills, above
• ability to troubleshoot software