search

josiahseaman / FluentDNA

FluentDNA allows you to browse sequence data of any size using a zooming visualization similar to Google Maps. You can use FluentDNA as a standalone program or as a python module for your own bioinformatics projects.
65 stars 7 forks source link

Project Website - Documentation #49

Closed josiahseaman closed 6 years ago

josiahseaman commented 6 years ago

From Tomasz: We would need to publish a more comprehensive “Project Web Page”. Since there is no GUI, a Project Web Page with usage documentation becomes even more important. This can exist within the Github as Wiki pages (advantage of this is archivability, GitHub can be archived into Zenodo https://zenodo.org/ ) or on a separate location. The page should contain:

This issue may have sub-issues or become a milestone.

josiahseaman commented 6 years ago

I like the idea of using github.io. I have had a bad experience with the github wiki, because it's not actually backed up or pullable in the same way as the code. I believe github.io actually exists as the gh-pages branch in the same repo, so the documentation and source code come together. It's a good solution, though in practice I find that I end up having two copies of the repo on my machine: one for code, one for gh-pages. Because they have no overlap.

I could possibly write more high level documentation (there's already a lot of low level details in the code). In this case, you want user documentation, not necessarily developer documentation.

josiahseaman commented 6 years ago

As I'm writing the paper, I want to add in many references to Supplemental figures. Perhaps these should be mirrored examples on the Project website. Reused content could be less effort. What do you think @photomedia?

photomedia commented 6 years ago

It is good to have documentation in the source code, that is great. However, there is absolutely a need for user documentation that can be used as a reference for how to use the software without having to find comments embedded in a dozens of files of source code. We need user documentation.

Yes, absolutely, it makes sense to use mirrored examples on the project web site from the what you want to use in the paper. Of course, the paper may need to go into details that aren't needed in the user documentation, and vice versa. For a paper, you will need to have references to figures, so it is good to to try to organize where these are posted, but you will also have to submit figures as TIFF images as well.

About the place for the user documentation: we could try to start with a wiki because that way we can work on it collaboratively, and then export that to a separate web page and/or a PDF to be included in the release. I also suggest we follow these instructions: https://guides.github.com/activities/citable-code/ to archive the release in Zenodo, which will give us a DOI for the code, as well as archive the documentation. If Zenodo doesn't archive the Wiki, we will just export the contents to HTML or PDF.

Does that sound like a good plan to you, @josiahseaman ?

photomedia commented 6 years ago

I have drafted an outline of the user documentation as a wiki page for now: https://github.com/josiahseaman/FluentDNA/wiki
We can collect the essential user documentation here first. Let's start by filling in as much information as we can about the basic functions with examples first.

josiahseaman commented 6 years ago

For Release 2.3.0 I moved the documentation to the front page Readme so that it was more noticable.