Improve structure of documentation for different target groups

[tomschr]

Situation

Thanks for this project, it looks really promising. :+1:

As you probably know, I'm the current maintainer of python-semver and I'm also a documentarian. That means, I care about documentation, I like to write them, improve them, etc.

As we are currently migrating the python-semver repository from setuptools to hatch, I also consulted your documentation. :slightly_smiling_face: However, I have some difficulties with it. Maybe it's only me. :wink:

For example, some of my problems were:

• To understand There is a list of features which is fine. However, I would like to get more details about this project before I use it. For example, what does this project aim for? As a replacement for setuptools? As a Python-only build framework? What's maybe NOT a good case for hatch? What are the design philosophies? How does it compare to other build frameworks in Python?
• To search for my use case (migration) Imagine, I want to migrate from setuptools to hatch. What should I do? What should I watch for? Which are the traps? What does hatch different than other tools? What things are supported and what's not?
• To consult the references The reference is good, but it didn't answer one question: what should I use when I want to have different scripts for different platforms? I searched for Platform overrides section, but the example was very brief and confusing to me. I would have appreciated a more complete example.

However, it's not limited to that. Consider it as a more of a "meta documentation" issue: what should it contain, how it should be structured, whom does it address.

Possible ideas and solutions

I'm aware, from the above description it sounds a bit foggy. That comes a bit from describing my experience and to give a more of a high-level overview.

From my own experience, I know that documentation can be hard to write and to structure. As such, to mitigate the structure problem, I'd like to suggest to look into the Diátaxis doc framework. Cited from their homepage:

The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.

In Diátaxis, each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.

This does not mean, we need to change the complete documentation in one single huge pull request. Quite the opposite. Each pull request should fix one problem in the documentation that works towards the above doc framework.

I could imagine the following changes that could be done more or less independently:

• Create a migration guide and explain what you need to move to Hatch.
• Rename/restructure "Introduction" towards a tutorial. Let the beginner know which steps are needed to create a hatch-powered project. Consult the doc framework in regards to what is needed for a tutorial.
• Rework some sections to create howtos. It could be written for different target groups. For example, a beginner does not need to know all the different config options at the first time. A beginner would probably like to know what is needed and how it can create a new hatch-based project.
• Distinguish between your target groups: intermediate users, plugin developers, project maintainers, ... or whatever groups you consider as important.
• Let the reader know right after the headline who this topic is for (target audience!) and what the goal is.
• Watch for titles that are ambiguous and find a better title.

• Create more showcases. You have one, but that's quite simple. What I'm missing are, for example, different platforms, building documentation, running pre and post commands, compile with Cython, interact or replace tox etc.

  A good showcase benefits in two ways: first, it serves as a good example in itself and people can use it right away. Second, it can also be referred in your documentation and explained in detail as a recommended, stable, and thoughtful example.

It does not mean all of the above items need to be implemented. They just serve as some inspirations. Of course, a project is never finished, and this also applies to the documentation. :wink:

Let me know what you think about. :slightly_smiling_face: I can also help with reviewing some pull request or help to set up the initial change.

Benefits

I think, the project will benefit from a good documentation in many ways:

• Advertisement Documentation is always underestimated as people focus on the software exclusively. However, clearly written documentation that is focused on user needs sells itself and shines well on the project itself.
• Find information quickly Time is valuable and everyone has too little of it. Having a good structured table of content, meaningful topic titles, separation of structure as suggested by Diátaxis, and a good search engine for the rest, helps to quickly find what you are searching for.
• Help and make users happy A happy user will spread the words and advertises it for you.
• Help users' needs Probably hatch can be used by different users which different levels of knowledge: Python beginners, intermediate users who just wants to build for different systems, and experts who must maintain a project. All have different needs and good documentation tries to help them.
• Give a guideline to contributors Every contributor has probably the same problem: where do I explain this new nifty feature in the documentation? A clearly structured documentation helps contributors to find their ways.

References

• https://diataxis.fr/

[ofek]

I'm going to post comments about how the documentation is currently hard to navigate to give myself more motivation to devote time to a large refactor.

[ofek]

https://github.com/pypa/hatch/issues/981#issuecomment-1744761966