happyflower's comments

happyflower | 4 years ago | on: Compare AsciiDoc and Markdown

Comparing AsciiDoc to Markdown (instead of for instance reSructured Text/reST) is clever, but I don't think there's any widespread controversy about the shortcomings of Markdown. So that's just an easy win.

I've seen this premise a lot (quoting from the article)

»The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts an author must grasp in order to be immediately productive.«

What relevant documentation markup languages have this issue?

If we already agree that documentation should be written as code, let's embrace it and not be scared of showing syntax. It's our tools that matter here - syntax highlighting, previewing, CI feedback.

I see much more that people writing markup languages get extremely motivated from their first victories with coding something.

Don't be afraid of showing people syntax -- Wikipedia got pretty far with a less-than-optimal markup language!

I think the real issue with AsciiDoc is something more along these lines: https://xkcd.com/927/

I'm working in a large organization where we are failing to streamline and spread documentation practices because of many different standards and practices popping up everywhere.

I like a lot how the Python community has centered around Sphinx and Read the Docs. It's great that for instance Sphinx support both Markdown and reST in that regards -- but then when things like Hugo/Docsy, AsciiDoc, Github Wikis, groovydoc etc. starts popping up, the unification of documentation practices in a large organization becomes harder -- and also of course across the specter of Open Source projects.

happyflower | 4 years ago | on: Why Computing Students Should Contribute to Open Source Software Projects

Students can make very big and positive contributions to Open Source and contributing to Open Source with a primary goal of benefiting the project is great. But if this is just a secondary goal, then I would politely say "no" to the offer.

If, however, the university would provide resources to ensure that contributions have the required quality and can assist maintainers with the added load, then it would possibly work! I could imagine that a direct link between maintainer(s) and university supervisor/lecturer would work well, so that maintainers can express their needs and priorities to someone who can handle/govern them in front of the learners.

happyflower | 5 years ago | on: 12 requests per second: A realistic look at Python web frameworks

ORMs give an affordability to write code faster. That may save time, but instead of saving time, you can also reinvest in better quality and performance. That's up to you and your team.

For instance, Django has prefetch_related and select_related. At almost every Django conference, there's a talk on this topic because it's so important and very underused/overlooked. But these are provided methods of the ORM.

Aside from that, there are wonderful introspection tools such as django-debug-toolbar to view the raw SQL and its performance.

It can be argued that if a solution written in Django hasn't had its database performance introspected with for instance django-debug-toolbar, then the solution isn't done. This is a small step with big rewards.

This introspection can easily identify where raw SQL is useful. But apply it late in process: As a project matures, the costs of converting some queries into raw/hybrid SQL are lower, as the statement is less likely to change. But keep these SQL statements in the models and managers, don't let them spill into views, template tags etc.

page 1