Closed ababaian closed 4 years ago
"├── doc # Source files"
The universal convention is the doc/ directory contains documentation and src/ contains source, this is confusing. Seems this directory is very small and not too late to change? Regardless would be useful to have documentation somewhere for how to use stand-alone modules and the whole thing (it's too complicated for README.md IMO). Maybe notebooks is an acceptable replacement if most people are familiar with them these days (I'm not). Notebooks documenting a module or procedure should have a name matching the module or procedure; dates are uninformative. What about a bin/ subdirectory for compiled binaries such as bvfilter and usearch. Handy to have them even if the source is there and buildable.
That was a typo, yes doc
will contain documentation. What I am still uncertain about is if we want all tool documentation to be in doc/
or instead have README.md
associated with a sub-module folder, this makes reading the code on github much more intuitive. See benchmarker module page.
Notebooks are not a replacement for documentation. A notebook is to document a one-off script or 'experiment' i.e. running a Divergence vs. Alignment rate series or generating a particular version of the pan-genome. It is the provenance for our data and figures.
How about always a readme.md and optionally a doc/ sub-folder, the readme is one line pointing at doc/ if applicable.
I'm a big fan of symbolic links
The container build script is also now in that folder. Dockerfiles are adjusted to be built out of
containers/
folder.The various analysis scripts we had floating around are all centralized to
src/
. This will be the home for tools in the future.Jeff I beat you to the push so please go over this and let me know if you're going to have any conflicts.