Review of PyApp documentation at PyConlineAU

pyapp-doc-review.md

Kathy reviews the PyApp documentation

Assumptions and approach to the review

• I have never used PyApp before so I am a total beginner
• The approach I'm using is to "reduce the time to hello world" for this tool - what will help get people up and running the fastest?
• The feedback is structured in terms of OBSERVATIONS of how the documentation felt, or was interpreted, and RECOMMENDATIONS for change.

First glance of the docs page

Page reviewed: https://docs.pyapp.info/en/development/

Observations

• Where would people be coming to this page from - for example, do they get directed to this page from PyPI? Anywhere else? What does that tell us about their user journey? What would someone be expecting to see on this page, and where do they go next? That is, where does this page sit in the user journey?

• I went to the page pyapp.info thinking that might be a "general" project page - and that the docs would be linked from there, but it just has some text on the page.

• I wanted to have a look at the code for the project, but there is no link to GitHub/other Git repo that I could see on the docs page. I can see that the build is passing, and code style etc (which is great!), but there isn't any link to the source code that I could see easily.

• I couldn't tell immediately what problems PyApp aims to solve, or where it adds value to my Python project. It says that it handles the "boring stuff", but I think that there needs to be a clearer overview section.

• The heading "What do we handle?" is where I saw the information that I was expecting to be under a "Features" heading.

• I felt like this section needed a "Who is PyApp for?" section, with benefits for different roles, like Python developers, Linux sysadmin folks, team leaders and seniors, enterprise architects and so on. Different roles will be looking for different things from PyApp, and this is a way to connect those together.

• I was expecting a link to Tutorials in the Docs - perhaps this is something that is coming, or in the pipleine, but after reading Get Started, I felt like I wanted a Tutorial or a run through on an application.

Recommendations

• Put some content at pyapp.info that is general project information, or redirect the top level / to docs.pyapp.info.

• Provide a link to the source code somewhere on the docs page

• Add an overview section which clearly outlines what PyApp does, and how it might fit into a project or environment setup process. For example "PyApp is intended to be used at [stage of project] to automate things such as [list of things]. This saves time and effort by [the benefits that PyApp provides, such as not having to manually handle multiple configuration files]. You might like PyApp if .... [there are specific use cases that PyApp solves for]. The comment about Django only makes sense to me once I have this broader overview.

• Change the "So what do we handle?" heading to be "Features", as people will be expecting a heading called "Features".

• In each of the features that are handled, I'd recommend bolding the feature and then providing the description. This might also work best in a list. The reason for this is that if people are working in software dev teams, they might need to make a recommendation to their Senior or Team Lead, and this makes it easy to copy/paste.

  • name of feature - description of feature
  • name of another feature - another description

Installation

Observations

• Are there any CLI options that can be passed to pip install that people might need to know about (in the Installation section_? Is there a particular pip version that is required to install pyapp? If so this should be listed in this section.

Getting started

Observations

• When the documentation mentions "App", it's not clear what is meant. Is it the Python files on a file system? That is, I think it needs to define what is meant by "App". Do you mean project or package? Those are the words I was expecting, but didn't see.
• When the documentation asks me to install CookieCutter, I'm not sure if this is part of the pyApp package or something separate. I'm guessing that it's a separate package, but it would be good to make this clear.
• In the "tip" to skip this if you just want info, this tip isn't clear to me. Do you mean "Skip installing CookieCutter if you would just like more information on PyApp, and you're not ready to apply it to
• In init.py it suggests using semantic versioning. Will all the readers know what semantic versioning is?

Recommendations

• Link Semantic Versioning to https://semver.org/ or similar

Recipes

Observations

• I didn't know what a recipe was in this context

Recommendations

• Explain what a recipe is, why you might use one.
• This is a good opportunity to engage with your audience - what types of recipes are they looking for? Get them to suggest new recipes as Issues on GitHub - it's a way to engage, encourage new contributions etc.

Extensions

Observations

• I wasn't sure what an extension was in this context. Why would extensions be developed instead of them being added to the core pyApp functionality? As a developer, when should I create an extension versus when should I add additional functionality to pyApp core?

Recommendations

Developers

Observations

• This felt like it should have been called "Contribution Guide" or similar. When I see a page called "Developers", I think it will provide me with a list of the developers who have contributed to the project.

• The list of steps to help developers get their PR accepted was really useful.

• There didn't seem to be a discussion list or place where developers could ask questions

Recommendations

• Rename to "Contribution Guide"
• Consider presenting the tips for developers as a checklist, and adding links to the recommended tools like pylint and pytest.
• Add a way for developers to make contact or to discuss contributions

Reference

Observations

• This seems exactly like what I would expect on a code reference - classes, methods and attributes. Without knowing pyapp in more detail, I don't have any other observations to offer here.