Skip to content

Commit

Permalink
Add info about contributing to the docs
Browse files Browse the repository at this point in the history
  • Loading branch information
adamltyson committed Oct 31, 2023
1 parent 45d98cd commit ef6de40
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 18 deletions.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
# Brainglobe main website
To contribute, please see the
[documentation](https://brainglobe.info/developers/index.html#to-improve-the-documentation).
41 changes: 23 additions & 18 deletions docs/source/developers/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,23 +16,6 @@ to [Adam Tyson](https://github.com/adamltyson), one of the core developers.

To add a new BrainGlobe atlas, please see the guide [here](/documentation/bg-atlasapi/adding-a-new-atlas).

## To improve the documentation

Documentation for BrainGlobe is **very important** because it is aimed at researchers who may not have much
computational experience. In particular:

- Installation, although simple via PyPI, assumes a lot (functional Python installation, CUDA installation etc.).
- Although most software can be run through a single command, there are a lot of steps, and so a lot to understand.
- There are a lot of parameters that can be changed, and their impact on the final results is not always obvious.
- It is not immediately obvious how to use the results of the pipeline to answer the particular biological question.

For these reasons (and others) every part of all software must be documented as well as possible,
and all new features must be fully documented.

### Editing the documentation

TBC

## To contribute code

### Creating a development environment
Expand All @@ -43,7 +26,7 @@ will create and activate a `conda` environment with the requirements needed
for a development environment:

```sh
conda create -n brainglobe-dev -c conda-forge python=3.10 napari
conda create -n brainglobe-dev -c conda-forge python=3.11 napari
conda activate brainglobe-dev
```

Expand Down Expand Up @@ -80,6 +63,28 @@ to the following conventions:
- Ask for a review from someone specific if you think they would be a particularly suited reviewer (possibly noting
why they are suited on the PR description)

## To improve the documentation

Documentation for BrainGlobe is **very important** because it is aimed at researchers who may not have much
computational experience. In particular:

- Installation, although simple via PyPI, assumes a lot (e.g. functional Python installation, CUDA installation etc.).
- There are a lot of parameters that can be changed, and their impact on the final results is not always obvious.
- It is not immediately obvious how to use the results of the pipeline to answer the particular biological question.

For these reasons (and others) every part of all software must be documented as well as possible,
and all new features must be fully documented.

### Editing the documentation
The documentation is hosted using [GitHub Pages](https://pages.github.com/), and the source can be found at
[GitHub](https://github.com/brainglobe/brainglobe.github.io). Most content is found under `docs/source`, where the
structure mostly mirrors the rendered website. To edit a page, please:
* Fork the repository
* Make edits to the relevant pages
* Create a pull request outlining the changes made

If you aren't sure where the changes should be made, please
[get in touch](https://brainglobe.info/contact.html#contributing).

## Further information
:::{toctree}
Expand Down

0 comments on commit ef6de40

Please sign in to comment.