JuliaDocs/Documenter.jl

Formulate a FAQ/troubleshooting page in the docs

Open

#2,138 opened on Jun 8, 2023

View on GitHub
 (0 comments) (0 reactions) (0 assignees)Julia (910 stars) (513 forks)batch import
Type: Documentationhelp wanted

Description

There are quite a few common pitfalls that come up over and over again. We should really just have a troubleshooting page. Some ideas of what should go there:

  • Docs are generally not deploying?
    • Are things showing up on the gh-pages branch?
    • Is DOCUMENTER_KEY properly set up?
    • Is CI for docs starting at all?
    • Is deploydocs running? If not, what error do you see? If yes, does it show git push to somewhere?
  • master shows up, but not tags?
    • Is TagBot working? Is it using DOCUMENTER_KEY?
    • Can you see the tags in your GHA logs?

Would be good to collect other common errors and issues people run into as well.

Contributor guide

Tech stack
None
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Familiarity with Documenter.jlUnderstanding of CI/CD for docs
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65
Research direction
Collect common pitfalls from existing issues and discussions. Identify the appropriate location in the docs structure to add a new FAQ page. Consider creating a markdown file and updating the documentation index. Ensure the content is well organized and covers frequent problems.