Improving Docs

[expede]

[Ported from the old Witchcraters Discourse]

---

@chouzar:

Witchcraft's documentation is already excellent and has extensive coverage for most functions and protocols. However due to the nature of the library, not everyone may be familiar with the more "elevated" patterns or lingo.

Some areas that may be given further exposition:

• Extended concept explanation (the abstract)
• Extended function usage (the implementation)
• Try to ground concepts within a use case (if appropriate)
• Provide alternatives within elixir or other Witchcraft abstractions (as a point of reference)

More extended docs usually mean extended code files, so some of these may be better suited as a documentation guide. Here are the elixir guides for documentation along with recommendations.

I'm personally not familiar with most of the concepts of the library so my current strategy is to just skim through the docs and find areas of confusion and ask around in this same thread.

The Witchcraft's README offers this dependency diagram:

Quark    TypeClass
    ↘    ↙
   Witchcraft
       ↓
     Algae

Quark looks pretty inoffensive, my guess is that it would be a good place to start; sounds like a plan?

---

@expede:

Quark looks pretty inoffensive, my guess is that it would be a good place to start; sounds like a plan?

Yeah, starting with Quark is a great idea IMO 👍 Also the functions are more concrete, so definitely the lowest learning barrier.