Adding documentation¶
You might have the best software in the world - but if nobody knows how to use it, what's the point? Documentation can always be improved - and we need your help!
Documentation form basics¶
BeeWare Docs Tools's documentation is written using MkDocs and Markdown. We aim to follow the Diataxis framework for structuring documentation.
The Diataxis framework consists of a quadrant of four forms of documentation. Our interpretation of it is as follows:
- Tutorial - A guided learning experience, with a specific project endpoint.
- How-to guide - Instructions that guide the reader towards a specific goal or outcome.
- Topic guide - A discussion of a single idea, explained in such a way that the underlying concepts are clear.
- Reference - Technical descriptions of specific APIs or other interfaces.
Choosing the right form¶
Before beginning a documentation contribution, it's important to identify which form is the best fit.
A tutorial is an introduction, particularly one focused at beginners, the goal of which should be getting them from a clean starting point to a finished product. It requires very specific instructions, and detailed explanations putting the information in context. You must assume nothing about the reader's experience with the tool being explained, although it's acceptable to assume some basic Python proficiency. There should be regular checkpoints where the reader can establish that they have succeeded in doing what you've described, and the success criteria should be clear. Known failure cases should also be clearly outlined, including explanations of any likely errors or problems the reader might experience. Things that change as a result of actions the reader has taken should be pointed out even if seemingly obvious toy you. Repetition is encouraged, especially if you're trying to establish a best practice or common processes. Explanations of internals should be avoided, as should alternative paths to the same outcome. A tutorial on baking cookies would be a specific set of instructions who has never baked before, and would need to account for things that an experienced baker would take for granted, such as the actual process of pre-heating the oven, or how long the cookies should be left to cool before eating.
A how-to guide should focus on a specific real-world use-case, and practical outcomes, not theoretical explanations. Unlike a tutorial, you can assume some familiarity with existing tools; the reader should be able to follow the guide from beginning to end and reach the goal, but they may need to have some existing knowledge to do so. It should include a set of concrete instructions or logical steps that need to be followed. A recipe is a good example of a how-to guide; there are many recipes for chocolate chip cookies, and they will all share common features, but any specific recipe should be possible to follow from beginning to end, and result in a consistent outcome. A good chocolate chip cookie recipe won't digress into the relative merits of different types of sugar or flour; it will include only the ingredients and instructions for baking a batch of cookies.
A topic guide describes a single subject or idea. It may include example code or instructions, but it is much more focused on providing a high-level picture of an overall landscape. It may include opinions and alternate perspectives, but the focus on the specific topic of the guide should be maintained. A topic guide on baking cookies might dig into the history of cookies as a baked product, explore that way that industrialized processes result in different types of cookies compared to homemade cookies, or suggest ways that cookies can be introduced into a broader diet.
Reference documentation is information oriented, describing specifics of operation of a tool library. They can quite often be generated from the code itself, but good API documentation may require further explanations and context. While it may sometimes include examples of usage, detailed explanations should be avoided. A reference guide in baking might describe the types of sugar that could be used, and detail their properties when used in baking. It would describe literal facts about sugar, but a broader discussion about choosing between sugar types should be the subject of a how-to or topic guide. The nutritional information found on most packaged foods would be considered reference documentation.
So, which form is the best fit for your contribution? Chances are a tutorial is not the right choice. You are most likely looking to submit a how-to or topic guide. Regardless, don't worry, we can help you narrow it down and choose during the proposal process.
Documentation style¶
BeeWare Docs Tools's documentation follows the guidelines outlined in the documentation style guide. This guide includes basic style and formatting, and the process for the spelling check. It also covers various Markdown syntax details, such as reference link syntax, tips for working with code blocks, and image handling.
Contributing documentation¶
Proposing new documentation
So you've got an idea about an improvement for BeeWare Docs Tools - how do you submit that idea for consideration?
Do your research¶
The first step is to search the BeeWare Docs Tools issue tracker for existing feature issues (issues tagged "enhancement"), documentation issues (issues tagged "documentation"), or Discussion threads to see if the idea has been suggested before. If it has, and you have new context or ideas to add, include them in the existing thread. If you would like assistance with your research, you can optionally ask in the #dev channel on the BeeWare Discord. We may be able to point you in the direction of existing threads, provide context of which you may not be aware, or connect your idea to a separate idea that might not be immediately obvious.
Discuss the idea¶
If you don't find any existing references to your idea, start a Discussion thread. Provide a high-level description of the purpose and use case for your idea. Include any thoughts you have on what the feature would look like, if implemented, such as the general shape of an API, or the visual appearance of the feature. If applicable, you should also include any research you have done on how your idea would manifest on different platforms.
Once the Discussion thread is opened, the team will respond. We will aim to provide at least an initial impression within one business day. If an idea is especially complex, a more detailed analysis might take up to a week. Events like holidays and conferences might cause those timelines to be slightly longer.
This is your opportunity to participate in a conversation about your idea. We may ask for more details or context. Other members of the community may also get involved in the discussion, providing other perspectives, suggestions or counter-proposals. The outcome of this discussion will determine the next steps.
It's important to understand that not all ideas will be accepted. The reason this process starts with a proposal is to avoid you putting in all the work, only to find out there is a reason your change won't be accepted.
This doesn't mean it wasn't a good idea! There may be technical reasons it can't be implemented. For example, we might reject an idea if:
- It would be difficult or impossible to implement reliably across all supported platforms; or
- It would be difficult to maintain, or maintenance would require access to technology or software that isn't widely available; or
- It serves a niche audience, but imposes significant overhead on other users.
If we determine that your idea isn't a good fit, it doesn't necessarily mean you should give up on it. While we may reject a specific idea, we may be a lot more amenable to adding a plugin interface or other extension point that would allow you to maintain the same feature as an external library. That way you can have the feature, but without the specific maintenance concerns or limitations of the feature becoming a constraint on the project itself.
Convert to a formal feature request¶
Once the discussion has reached a consensus on the form of a feature, you can create a new feature request issue, in the BeeWare Docs Tools issue tracker, that summarizes the discussion, linking to the discussion for context.
You don't have to implement your feature proposal yourself; you can open an issue with the details of what you're proposing. However, simply posting the issue doesn't mean it's going to be implemented for you. You'll need to wait for it to potentially get picked up by someone else interested in the same feature, whether that means another community member or the core team; however this is not guaranteed to happen. If you want the guarantee implementation, you'll need to implement it yourself, or pay someone else to implement it for you.
Building documentation
Building BeeWare Docs Tools's documentation¶
To build BeeWare Docs Tools's documentation, start by ensuring you have the prerequisites, and then follow this quickstart to set up a dev environment (or, for a more detailed explanation, start here).
You must have a Python 3.13 interpreter installed and
available on your path (i.e., python3.13 must start a
Python 3.13 interpreter).
BeeWare Docs Tools uses tox for building documentation. The following tox
commands must be run from the same location as the tox.ini file, which is in
the root directory of the project.
Live documentation preview¶
To support rapid editing of documentation, BeeWare Docs Tools has a "live preview" mode.
The live preview will build with warnings!
The live serve is available for iterating on your documentation updates. While
you're in the process of updating things, you may introduce a markup issue.
Issues considered a WARNING will cause a standard build to fail, however, the
live serve is set up to indicate warnings in the console output, while
continuing to build. This allows you to iterate without needing to restart the
live preview.
A WARNING is different from an ERROR. If you introduce an issue that is
considered an ERROR, the live serve will fail, and require a restart. It will
not start up again until the WARNING issue is resolved.
To start the live server:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
This will build the documentation, start a web server to serve the documentation, and watch the file system for any changes to the documentation source.
Once the server is started, you'll see something like the following in the console output:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Open a browser, and navigate to the URL provided. Now you can begin iterating on the documentation. If a change is detected, the documentation will be rebuilt, and any browser viewing the modified page will be automatically refreshed.
docs-live is an initial step
Running docs-live to work with the live server is meant for initial iterating.
You should always run a local build before submitting a pull request.
Local build¶
Once you're done iterating, you'll need to do a local build of the documentation. This build process is designed to fail if there are any markup problems. This allows you to catch anything you might have missed with the live server.
Generating a local build¶
To generate a local build:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
The output of this build will be in the _build directory in the root of the
project.
Generating a local translated build¶
BeeWare Docs Tools's documentation is translated into multiple languages. Updates to the English documentation have the potential lead to issues in the other language builds. It is important to verify all builds are working before submitting a pull request.
To generate a build of all available translations:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
The output of each language build will be in the associated
_build/html/languagecode directory, where languagecode is the two- or
five-character language code associated with the specific language (e.g. fr
for French, it for Italian, etc.).
If you find an issue with a single build, you can run that individual build
separately by running tox -e docs-languagecode.
For example, to build the documentation in only French:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
The output of a single-language build will be in the _build directory.
Documentation linting¶
The build process will identify Markdown problems, but BeeWare Docs Tools performs some additional "lint" checks. To run the lint checks:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
This will validate the documentation does not contain:
- dead hyperlinks
- misspelled words
If a valid spelling of a word is identified as misspelled, then add the word to
the list in docs/spelling_wordlist. This will add the word to the
spellchecker's dictionary. When adding to this list, remember:
- We prefer US spelling, with some liberties for programming-specific colloquialism (e.g., "apps") and verbing of nouns (e.g., "scrollable")
- Any reference to a product name should use the product's preferred capitalization. (e.g., "macOS", "GTK", "pytest", "Pygame", "PyScript").
- If a term is being used "as code", then it should be quoted as a literal
(
like this) rather than being added to the dictionary.
Writing documentation
These are the steps to follow to write your documentation contribution to BeeWare Docs Tools.
Existing documentation¶
If you're editing the existing docs, you'll need to locate the file in the
/docs/en directory. The file structure follows the page structure, so you can
locate the file using the documentation URL.
Open the file in your editor, and find and update the intended text.
For small fixes, such as typos or grammar, you can make the fix and submit a pull request, without necessarily needing prior discussion.
For more substantial changes, you'll want to follow the proposal process to let us know what you have in mind, and allows us to discuss it.
Writing new documentation¶
If you're writing entirely new content, you'll want to follow the proposal process to provide us with an opportunity to work with you on what you're interested in contributing, how it fits into the existing documentation, and what form of documentation makes the most sense.
Once approved, you'll write up your new documentation.