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
nice:
https://docs.masoniteproject.com/ <https://docs.masoniteproject.com/>
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
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/U6QJC5RDXQB6T2CIUXPY6S2SNS5LTPVK/
Code of Conduct: http://python.org/psf/codeofconduct/