camelot-dev / camelot-dev/camelot

Updated documentation idea / installation screencasts

Open
#479 2 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Python
Stars
3.8k
Forks
546
Avg merge
3d 17h
Merged PRs (30d)
3

Description

Hello Camelot users / devs! I hope you're all off to a good start for the year.

For far too long I've been meaning to look at the Camelot docs to see if I could contribute to them and in the last few days I looked into what they would look like if ported to Mkdocs from Sphinx. I specifically tried out [Material for Mkdocs](https://squidfunk.github.io/mkdocs-material).

My initial attempt is in [this fork](https://github.com/nmstoker/camelot) and the results can be viewed here:

http://about.nmstoker.com/camelot/

I've two main points in mind with this:

* Port over to mkdocs, which as a way of writing/updating docs has a fairly low barrier to entry and produces a really smart modern look with minimal effort
* Explore ways to help clarify the installation steps & common issues

I'm mainly done with the first point and have made a start with the second.

For the second, I expect things will change over upcoming releases but right now I find that ignoring the "[base]" option and doing the steps manually with pip works better - otherwise pip can easily end up installing an older version due to some confusion around dependencies.

One idea I had to help guide people with installation is to embed platform specific [asciinema](asciinema.org/) style screencasts (they look like a video but embed the terminal text, so are pretty compact to include). The layout, content and a couple of recordings need further effort on my part to get it right (eg re-record at a correct screen size) but I hope you'll get the general idea from what's there already on these two pages:

* http://about.nmstoker.com/camelot/user_guide/install-deps/
* http://about.nmstoker.com/camelot/user_guide/install/

Anyway, would be great to hear thoughts / feedback on this.

Contributor guide

No contributing guide indexed for this repository

Research direction

Review the linked fork and rendered documentation, especially the install-deps and install pages, to understand the proposed MkDocs migration and installation guidance. Done would require an agreed documentation approach, clarified installation steps, and suitable platform-specific screencasts.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.