How to describe errors in documentation
Nobody has claimed this yet.
- Dominant language
- CSS
- Stars
- 15
- Forks
- 49
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 3
Description
When documenting a function for Tarantool reference, we have the "Possible errors" section. But for now we don't have a unified style of describing them. I think, we should agree on how to do this and update our documentation guidelines.
Linked issues:
https://github.com/tarantool/doc/issues/1703#issuecomment-747071946
https://github.com/tarantool/doc/issues/1348
@ veod32 in https://github.com/tarantool/doc/pull/3024#discussion_r924208098 says:
Possible errors can be related to the entire function/method, not necesserily to the misuse of some parameters.
See, for example,
https://www.tarantool.io/en/doc/latest/book/connectors/cxx/tntcxx_api/#public-methods
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/pairs/
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the linked issues 1703 and 1348, the discussion in pull request 3024, and the referenced C++ and Lua API documentation examples. Define a consistent style for the “Possible errors” sections and update the documentation guidelines once the scope is agreed.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100