Task #9835 (closed)
Opened 12 years ago
Closed 11 years ago
BF docs improvements
Reported by: | jamoore | Owned by: | hflynn |
---|---|---|---|
Priority: | critical | Milestone: | OMERO-4.4.7 |
Component: | Documentation | Version: | n.a. |
Keywords: | n.a. | Cc: | mlinkert, crueden-x, sbesson, rleigh |
Resources: | n.a. | Referenced By: | n.a. |
References: | n.a. | Remaining Time: | n.a. |
Sprint: | n.a. |
Description (last modified by hflynn)
Remaining issues following new 4.4.5 Docs release on Dec 10th:
Front Page
- Is the link to genomebiology for "OME Data Model" on the front page really the best link? (also first paragraph under Goal of B-F). (Maybe this comes post-BF as a general "OME-XML" doc effort" - YES, not for here)
User
- "Other applications" could use a really nice table possibly with logos.
Developers
Remaining issues to be tackled by Melissa e.g. change MacPort? recommendation to HomeBrew? and make sure all the commands/methods are up to date.
Formats
More text required to explain dataset structure table?
New content (separate PR?)
- Include request for sending example files.
Change History (15)
comment:1 Changed 12 years ago by jmoore
- Cc sbesson rleigh added
- Description modified (diff)
comment:2 Changed 12 years ago by mlinkert
- Owner changed from hfylnn to hflynn
comment:3 Changed 12 years ago by hflynn
- Description modified (diff)
comment:4 Changed 12 years ago by crueden-x
As requested by hflynn and sbesson, here is the complete list of .txt files from the Bio-Formats repository, what they do and if/where they should move.
Migrate
components/bio-formats/doc/export/*.txt: Documentation on using the Bio-Formats writer API.
components/bio-formats/doc/reader-guide.txt: A guide to coding your own file format reader, written by @mlinkert. Last updated November 2011.
components/bio-formats/doc/using-bioformats.txt: A guide to using the Bio-Formats API, written by @mlinkert. Last updated July 2012.
components/bio-formats/doc/whats-new.txt: A list of changes for each release.
components/scifio/cppwrap/readme-*.txt: Usage instructions for Bio-Formats C++ bindings for various platforms.
Partially migrate
components/bio-formats/doc/metadata-guide.txt: A document explaining how Bio-Formats metadata, which I never finished. Should either be migrated or deleted (with existing content merged into the "Goal of Bio-Formats" page).
components/bio-formats/doc/samples-needed.txt: List of sample data needed for each file format. Last updated July 2012. Merge with individual file format pages (which also have a list of what "We'd like to have"), rather than maintaining separately.
components/bio-formats/doc/meta/*.txt: Autogenerated Trac pages describing the supported metadata fields for each file format. I believe @mlinkert is working on migrating the autogeneration of these to sphinx, so they shouldn't have to be done by hand.
components/bio-formats/doc/testing-procedure.txt: Document describing test procedure. Last updated October 2009, so very likely does not reflect today's actual testing procedure. Delete?
components/test-suite/doc/release-steps.txt: Document describing automated and manual tests performed prior to a Bio-Formats release. Last updated September 2009, and does not reflect today's actual testing procedure. Merge anything relevant to up-to-date release process document, then delete?
**/README.txt, **/readme.txt: These files are automatically displayed by GitHub? when browsing that directory, which means they cannot move. However, some of them might make sense to largely migrate their *contents* to the documentation pages, and then edit the readme itself to provide a link to the main content.
Do not migrate
**/LICENSE.txt: For legal reasons, these licenses must remain. They are a standard of Maven and license-maven-plugin.
**/CMakeLists.txt: These are build files for CMake.
components/forks/**/*.txt: Text files that are part of a forked project. We try to keep our changes to these forked project to an absolute minimum.
components/native/bf-itk-*/slicer-license.txt: Third party copyright attribution.
components/autogen/src/*.txt: Sources for autogenerated documentation.
components/loci-plugins/src/**/*.txt: Configuration files for the Bio-Formats ImageJ plugins.
components/loci-plugins/utils/macros/*.txt: ImageJ example macros.
components/scifio/cppwrap/*.txt: Configuration files defining how to autogenerate the Bio-Formats C++ bindings.
components/scifio/src/loci/formats/*.txt: Configuration files defining available readers and writers.
comment:5 follow-up: ↓ 8 Changed 12 years ago by hflynn
There are FAQ links which will need to be updated when that content is migrated to the main docs
comment:6 Changed 11 years ago by hflynn
- Description modified (diff)
- Summary changed from BF docs (round 2 from PR 190) to BF docs improvements
comment:7 Changed 11 years ago by hflynn
- Description modified (diff)
comment:8 in reply to: ↑ 5 Changed 11 years ago by hflynn
FAQs updated with new links
Replying to hflynn:
There are FAQ links which will need to be updated when that content is migrated to the main docs
comment:9 Changed 11 years ago by hflynn
- Description modified (diff)
comment:10 Changed 11 years ago by mlinkert
See https://github.com/openmicroscopy/bioformats/pull/324 for some of the developer documentation changes.
comment:11 Changed 11 years ago by hflynn
The remaining issue is where to put the request for example files. It would nice to get that added and then I think we are sorted for 4.4.6 - I'm not very taken with the table options in Sphinx, I'm happy to leave the other applications as a list of links for now.
comment:12 Changed 11 years ago by jmoore
hflynn: understood on the table front. After adding the "example file request" bit via PR, feel free to close, but let's make sure the OME-XML section has been added to the appropriate ticket.
comment:13 Changed 11 years ago by hflynn
See https://github.com/openmicroscopy/bioformats/pull/331 for final PR for this ticket
comment:14 Changed 11 years ago by hflynn
See #10099 for fixing the front page issue re: OME data model link
comment:15 Changed 11 years ago by jmoore
- Resolution set to fixed
- Status changed from new to closed
+1