Documentation Review - What Do We Want?

[Jegelewicz]

Currently documentation is divided into several sections:

Documentation - Descriptions of specific database tables and field definitions. Also available via info-links from the Arctos Database on pages with permissions (nitty gritty technical stuff)

How-To - Learn the steps to using Arctos better here! Written by Arctos users. (step-by-step directions for getting stuff done)

Best Practices - Learn how to use Arctos better here! (what to do when you have options and don't know the best path to take)

Tutoiral Quick Bites - How-To in video format (step-by step directions for getting stuff done)

Resources - These are How-To pages organized by topic (a place to find whatever someone decided was all thing "media" or "GitHub" together)

Over time, these have started to overlap and grow in size. Are we happy with this kind of organization or do we want a single "Agents" document that includes technical detail, how tos for any kind of Agent work and best practices just part of that? Does anyone even read this stuff?

I've been trying to tease things out and make documentation more user-friendly for incoming collections, but I am not sure if what I am doing is helpful. I think we need a general community discussion about how to handle documentation and we also need more participation in its creation.

[Jegelewicz]

Added to AWG Agenda for December 9, 2021

[Jegelewicz]

Also, how should it function - I like how GBIF's intro works - https://docs.gbif.org/course-introduction-to-gbif/en/about-gbif-2.html Our search/index on the left side doesn't scroll correctly.

[Jegelewicz]

@mkoo @campmlc this is where I think @ekrimmel could really do us a solid. Our documentation has become fragmented (beyond often being out of date) and we need a cohesive plan for making it work along with things like ArctosDB/arctos#5450 and https://github.com/ArctosDB/internal/issues/225

[dustymc]

Does anyone even read this stuff?

I do, and being able to point to documentation rather than drudging up an answer saves me a lot of time. (And at least one recently new collection didn't seem to much get stuck until the documentation ran out...)

Over time, these have started to overlap and grow in size. Are we happy with this kind of organization or do we want a single "Agents" document that includes technical detail, how tos for any kind of Agent work and best practices just part of that?

At some point the idea was to separate the WHAT (mostly stable, maintained by me, doesn't necessarily tell you how to use stuff) from the HOW (user-generated, more or less expected to become stale, definitely expected to be a partial viewpoint). I think I still like somehow identifying the authoritative(ish, probably) stuff, but I'm not sure I care how.

I still haven't quite decided if best practices deserve their own pigeonhole or if we've just denormalized /docs.

how should it function

What resources are we realistically bringing to the table? I'd like to just do whatever our documentation team's engineers tell us to, but realistically I think we probably need something super-simple that people with full-time jobs can build, operate, and maintain.

Our search/index on the left side doesn't scroll correctly.

And I'll take that as an indication that even that little bit of wrapper is more complexity than we can really maintain. (And minor changes to content change URLs and anchors, which I know is beyond out ability to maintain.)

I keep coming around to the idea that a github wiki is worth a hard look. There's nothing to build, our markdown pages should mostly just work, and user access wouldn't change, which are all YAY! Beyond that though, I know nothing....

[campmlc]

Agree. What is latest word from her?

…

On Mon, Jan 16, 2023, 4:29 PM Teresa Mayfield-Meyer < ***@***.***> wrote: * [EXTERNAL]* @mkoo <https://github.com/mkoo> @campmlc <https://github.com/campmlc> this is where I think @ekrimmel <https://github.com/ekrimmel> could really do us a solid. Our documentation has become fragmented (beyond often being out of date) and we need a cohesive plan for making it work along with things like ArctosDB/arctos#5450 <ArctosDB/arctos#5450> and ArctosDB/internal#225 <ArctosDB/internal#225> — Reply to this email directly, view it on GitHub <#251 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADQ7JBAYNX3AZJOGI2LDAZDWSXKU3ANCNFSM5ICTCFRA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[mkoo]

This topic seems to best be discussed in realtime. The current site was built recognizing that topics overlap which is why it has the large search bar so users can search across all those avenues and come up with all relevant pages. But I have looked into some other frameworks for docs many of which were not available when we built the handbook. I like some of the versioning control and printable/ exportable options in several of them! A discussion within the Documentation committee seems the most relevant place