[Python and Ladder]: 🔧 Documentation improvements: update examples & structure for human-errors

[revantharunachalam]

The documentation for the human-errors package currently gives a solid overview but could benefit from enhanced direction and clarity—especially for new adopters and for expanding use-cases. Improving the docs will make the project more accessible and encourage contributions.

What needs improvement

• The README and PyPI project description cover usage of json_dump, toml_dump, yaml_dump, and the CLI tool, but some sections lack step-by-step detailed examples for typical workflows (e.g., integrating with a CI pipeline, custom renderer use).

• Formatting and structure vary between sections: headings, code blocks, and outputs could be more consistently styled (for example, unified indenting, consistent use of language comments, and clearer context).

• The “Contributing” section exists (under Contributing on PyPI) but could be expanded: describe local setup (linting with ruff, type checking with ty, tests with pytest), branch naming, PR review criteria, and how to add new format support.
  PyPI

• Compatibility/version information is minimal: while the package “Requires: Python >=3.12” is listed, it would help to document any differences/limitations when using Python 3.13+, or if certain renderers (like the miette-style) require extra setup.
  PyPI

• Navigation could be improved: a table of contents or sidebar (if using a docs-site generator) would help locate examples, CLI usage, and custom renderer docs faster.

Proposed improvements

Update the README to reflect:

• latest installation steps (pip install human-errors)

• typical usage patterns (parsing a config file, catching a decode error, using the CLI tool)

• show full code snippet + output in a consistent format

• Add a “Getting Started” section for newcomers with links to full examples for JSON, TOML, YAML, CLI

• Standardise headings and formatting across docs: e.g., use ## for main sections, ### for sub‐sections, wrap code blocks with language specifier (```python)

• Expand the “Contributing” section: local dev setup, lint/format commands, how to run tests, how to add support for a new file format

• Add a section “Version & Compatibility” to document Python version support, note any known caveats or future plans

• If desired, create a simple docs site navigation or table of contents (could be added in the README or a docs / docs-site folder) for “Installation | Usage | CLI | Custom Renderer | Contributing | Version Info”

Additional context

I’d be happy to tackle this and submit a pull request. Please let me know if you have any style guidelines or preferred docs tooling (Markdown only vs MkDocs/Sphinx) so I can align with the project’s standards.

Thanks and Regards,
Revanth Arunachalam,
Python and Ladder.

[NSPC911]

I dont really mind a PR for this

This was something I whipped up quickly because many Discord servers I showcased it in, wanted it to be pluggable.

I'm not sure in the docs part though, this is too simple of a project, but I will see what you want to create.

Tests don't exist for now, this is quite simple but I haven't entered the rabbit hole for now.

I want to see a PR before I make any final decisions.

[revantharunachalam]

Thanks @NSPC911 ,
We are creating a community for the Python developers mostly for beginners and young startups to support,

1. Testing and resolving bugs
2. Feature implementation
3. Documentation and Tutorials
4. Packaging and publishing
5. SEO and Marketing

As in the initial stage, we are going through small interesting python packages in PyPi which are open source and trying to contribute them with our services for free. If you are okay with this, would you please create a document/good first issue for this issue ticket. Let's me know if you have any concerns.

Thanks and Regards,
Revanth Arunachalam,
Python and Ladder.

[NSPC911]

trying to contribute them with our services for free

that's just how open source works

If you are okay with this, would you please create a document/good first issue for this issue ticket.

do you want me to tag this issue with good first issue?

[revantharunachalam]

@NSPC911 ,
It's okay, Documentation tag is enough for this. We shall use good first for some minor bugs right?

[NSPC911]

i don't really mind, i just like to do whatever i like to do. it's not like the tag says good first bug anyways