camelot-dev / camelot-dev/camelot
Updated documentation idea / installation screencasts
- 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