Conventions for tool names and descriptions
Hi all, Are there any guidelines on tool names and lengths? There is a tendency due to the way the tool name and description are run together in the left hand pane listing to write the description as an extension of the name: e.g. Name: Select Description: lines that match an expression Many of the default tool's descriptions do not make sense without the name. I brought this up in in this thread at the end of last year, about how the tool shed showed these fields: http://lists.bx.psu.edu/pipermail/galaxy-dev/2010-December/004012.html http://lists.bx.psu.edu/pipermail/galaxy-dev/2010-December/004017.html http://lists.bx.psu.edu/pipermail/galaxy-dev/2010-December/004019.html Again based on observation, the tool names are generally up to four words, short enough to fit on one line in the left hand pane. Description lengths vary from nothing (e.g. the "Indel Analysis" tool) to over four lines (e.g. the "Cuffcompare" tool). Note the line count depends on font settings and if the user has altered the left hand pane column width. Clearly there is a balance - shorter means more tools fit on screen at once making navigation easier, longer makes it less likely the user will have to click on each tool to read its more details description to find what they are looking for. This is also an issue for browsing the tool shed - I had an email exchange with Alex about this tool of mine: Name: Filter sequences by ID Description: from a tabular file I wrote it like this so that once installed the entry in Galaxy's left hand pane reads "Filter sequences by ID from a tabular file", where I mean the ID comes from a tabular file (not the sequences). This is however ambiguous, Alex interpreted it as meaning the sequences come from a tabular file. Including the words FASTA, FASTQ, or SFF in the text would help, but also makes the tool entry in the left hand pane bigger. Are there any guidelines for desirable name/description lengths? Having a tool mock-up in the Tool Shed would help when browsing potential tools of interest (enhancement issue 565), but that isn't likely to happen in the short term: https://bitbucket.org/galaxy/galaxy-central/issue/565 Thanks, Peter
participants (1)
-
Peter Cock