Improve documentation
TuomasBorman opened this issue · 12 comments
After we moved similar functions under same manual page, we lost some "hidden" parameters that were described under ...
. That is because one manual page can have only one description for each parameter, i.e., if we have documentation coming from multiple R files, descriptions of ...
parameters are not merged; the documentation has only one description of ...
.
--> Check these problems. If this kind of issue is found, ensure that all the documentation can be found from manual page (merge descriptions manually to single R file).
For instance, agglomeration functions are under single "agglomeration" manual page. However, it seems that agg.na.rm parameter is missing from [here](https://microbiome.github.io/mia/reference/agglomerate-methods.html even though it is listed here
I'd also probably split at least agglomerateByRank
and agglomerateByPrevalence
functions in separate pages, as for example, detection
and prevalence
parameters are not required for agglomerateByRank
(?).
The idea was to harmonize the naming and documentation so that it is intuitive for user that these agglomerate* function do similar things. We cannot avoid having documentation pages which include parameters that are not shared with every function in the page; they are very common. But this is something that we can discuss what is the best way to organize the manual. Updating manuals was already in task list.
Given that other functions like estimate*
and calculate*
have separate manual pages, and if the intention is to harmonize the package documentation, separating the agglomerateBy*
functions will provide several benefits such as simplicity, specific info about fxns and ease of maintenance.
However I also see a WIP where we index estimate* docs into addAlpha, so I am a bit unsure of the consequences on harmonization. Does this imply we index other functions of nature fxn* such as calculate*
, agglormerate*
, convert*
, get*
, import*
, run*
, split*
etc. This is imperative if we need to ensure consistency in the code and perhaps the docs.
estimate* functions were merged into addAlpha. So there is no separate methods for estimateDiversity, estimateDominance etc anymore; all alpha diversity indices are calculated with addAlpha
The initial idea was to harmonize the documentation, but as Artur pointed out, there are drawbacks. Since we already harmonized the naming, that should be already clear that functions named similarly do similar things.
So I would prefer simplicity and clarity. That is achieved probably by separating agglomerateByRank and agglomerateByPrevalence functions since they have too many different parameters. Also the same goes with import* functions. So the changes that we made previously were suboptimal. However, it should be quite simple to revert this since we only modified the targeted documentation name (@Rdname tag).
@Daenarys8 Can you go through mia documentation and give suggestions how to proceed? https://microbiome.github.io/mia/
The documentation is currently a mess.
I am thinking we need to restructure the documentation. Placing emphasis on providing a clear, logical, and comprehensive guide that users can easily follow. We can start with an Introduction and Overview section/menu that gives a high-level summary of the mia package, its purpose, and key features, along with installation instructions. Follow this with a Getting Started section/menu that introduces users to TreeSE objects, providing a quick start guide and basic usage examples to get users up and running quickly.
The next section/menu Workflows, could include Data Preparation, which should focus on importing and preprocessing data, managing metadata, and performing data normalization, agglomeration and transformation to ensure users can properly prepare their datasets for analysis. After data preparation, we include an analysis subsection that covers core analysis functionalities such as alpha and beta diversity analysis, taxonomic analysis, etc.
The next section References detailing user accessible methods.
Optionally we could address common user questions and issues in a FAQs and Troubleshooting section, offering solutions to common problems and best practice tips. Finally, the Contributing and Community side navigation with guidelines for contributing to the package, a code of conduct, citations and links to community resources can remain the same.
However this is just a suggestion and very open to scrutiny and improvements.
Thanks for the suggestion! Hmmm, that sounds nice, but we should avoid doing overlapping work. The things that you described are already in OMA.
We should keep the mia documentation as simple as possible, but currently the problem is that there might be missing parameters, unclear explanations etc. So I suggest to
- Check if we should separate documentation of agglomerateByPrevalence & agglomerateByRank
- Check explanations if they are clear enough
- Use @inheritparam
I think we should separate docs. Also the explanations can be improved. Should i prepare a PR for this? It will also pickup from #462
Yes, please. This also is related to things that we discussed in Mattermost privately (the description should be unified: the class of input, what the parameter does, details, default value.). We can discuss more if you feel so
@Daenarys8 the status of this one?
Perfect. Please close this after the PR is merged.