On 30/04/2021 07:06, Abdur-Rahmaan Janhangeer wrote:
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