On 30/04/2021 14:29, Rob Cliffe via Python-ideas wrote:

On 30/04/2021 07:06, Abdur-Rahmaan Janhangeer wrote:

The Masonite docs for example is quite

I read as far as the 4th sentence:
    "Use it for your next SaaS!" [no link atached] What on earth (I wanted to use a stronger expression) is an SaaS? I'd never heard of it. OK, Google told we what it stood for, but I don't feel any the wiser. Rob Cliffe 

It means "mainframe". If you get an account on their computer, you're allowed to log in and pay to use the software. It's very modern: at last, the value of free, open-source software can accrue to rich industrialists, for whom we should all be working in our spare time.

I'm with you that the writing in the Masonite docs is not an example to follow. I only got as far as "actual batteries included" before doubts set in. Then the writer loses control of the sentence structure, obscuring the thought he began. However, visual style not literary content is the question.

The visual style is quite like the existing Python docs prepared in ReST (e.g. https://docs.python.org/3/reference/expressions.html). The Sphinx "Alabaster" theme is even cleaner, but intended in part, I think, as a blank canvas for your branding. I prefer the way the sidebar scrolls independently in the Masonite site. I found no examples of images, diagrams or tables to compare. I would not say there was much wrong with the Python visual style, but then I'm used to spending hours in the (downloaded) documentation.

Is it really just GitBook that we are slightly admiring? You would not, I think, want to re-write the ReST documents in GitBook, just to get a cleaner look. Time from someone clever with CSS in Sphinx may be all it takes.

If you follow the documentation link on the home page to https://www.python.org/doc/, much of that links to the wiki, which in my opinion does look a bit cobwebby. Style is only part of problem: the size and proportions of text look pokey to me. Here the content does not read very well, being crowd-sourced I imagine without much editorial control. (E.g. https://wiki.python.org/moin/BeginnersGuide is unsure of its level: veering from "if you've never programmed before" through to inviting patches.) Were we including the Wiki in this?

Jeff Allen