Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rationalise documentation #392

Open
widdowquinn opened this issue Apr 27, 2022 · 2 comments
Open

Rationalise documentation #392

widdowquinn opened this issue Apr 27, 2022 · 2 comments
Assignees
Labels
documentation documentation is unclear or incomplete
Milestone

Comments

@widdowquinn
Copy link
Owner

Summary:

We'd like to rationalise the documentation to make our lives, and users' lives, easier.

Description:

Some of the existing documentation is possibly overlong/in the "wrong" place, so we might consider three strands of documentation going forward:

  • ReadTheDocs
    • these are canonical user-level docs
    • how do you install (in detail)
    • how do you use each command (in detail)
    • how do you perform analyses (in detail)
  • README.md
    • this is a brief description of/introduction to the package/software
    • how do you install it?
    • how do you use it?
    • who wrote it?
    • what is the licence?
    • where are the docs?
    • where can I get help?
    • what if I want to contribute?
  • Wiki
    • these are intended to be relatively dynamic documents, mostly related to development, but with some user support
      • user-facing stuff, like FAQs etc. might start on the wiki, but migrate to RTD over time
    • what is the project roadmap?
    • what are our coding style choices?
    • how do we do tests/logging/etc.?
    • how do we manage issues, etc?
    • how do we integrate with CI/project management tools, etc.?
@widdowquinn widdowquinn added the documentation documentation is unclear or incomplete label Apr 27, 2022
@widdowquinn widdowquinn added this to the 0.3.0 milestone Apr 27, 2022
@baileythegreen
Copy link
Contributor

baileythegreen commented Apr 29, 2022

The current README has this table of contents:

Table of Contents

@widdowquinn From the conversation the other day, and the outline in the wiki, I think these sections of the README should be reduced/moved elsewhere:


The non-standard installation details could go into the wiki.


This might go into too much detail for the README, especially if it should eventually also detail SLURM stuff.


(This one maybe needs to stay; it depends a bit on the default version of pyani for the repo, I think.)


This section seems like it should either come earlier in the README, or be in the wiki:

@peterjc
Copy link
Collaborator

peterjc commented Apr 5, 2023

See also the CONTRIBUTING.md convention encouraged by GitHub which would hold or at least point to developer centric information like coding style, CI setup, issue management.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation documentation is unclear or incomplete
Projects
None yet
Development

No branches or pull requests

3 participants