[Bigbang-dev] Documentation organization

[Nick Doty]

Thanks Seb for getting this going! It's so nice to read documentation in
this format, rather than spread haphazardly around readme and wiki pages.

On Fri, Oct 8, 2021 at 4:11 PM Sebastian Benthall <sbenthall at gmail.com>
wrote:

> Hello,
>
> New documentation us up on RTD, including autodocs for the code docstrings
> and the README, imported.
>
> https://bigbang-py.readthedocs.io/en/latest/
>
> Now that we have a location to put more expansive/complete documentation,
> we can have dedicated pages for issues, such as the data ingress/egress
> <https://github.com/datactive/bigbang/issues/414> we support.
>
> Currently, all of our documentation is in the README, which has gotten
> quite long.
>
> We have some options:
>  - (a) move material out of the README into dedicated pages that are
> rendered to the docs, keeping the README light, with "must have"
> information and links to the docs for other topics.
>  - (b) maintain information redundantly in the README and in Sphinx
>  - (c) Status quo: keep using the README for almost everything except
> autodocs.
>
> My preference is for option (a).
>
> I wonder how you all feel about the best way to organize the docs.
>

I'm fine with option (a). I have noticed that documentation on development
(running tests, code of conduct, formatting, etc.) isn't included in the
Readthedocs pages yet. Is that something we want to move over? Or do we
think of the readme as primarily for bigbang developers and readthedocs as
primarily for bigbang users?

The API documentation is organized by file/library, which makes sense, but
I'm not sure how easy that is for people to understand. Should we have an
overview of how the code is organized so that someone new to the project
knows what to look for where? E.g. mailing list crawling is done within
these 4 files, archives and analysis is in these, these files were
experimental and aren't regularly used, etc. Can Sphinx accept some extra
text/context in the index page of the autogenerated library docs?

—npd
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ghserv.net/pipermail/bigbang-dev/attachments/20211119/d28d8d16/attachment.htm>