Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to Design Software Good

haiku-os.org

Post reply on HN
Print view View original

71–80 of 191 posts

Re: How to Design Software Good

#71

Post by SyneRyder »

lemming wrote: post #56
nayuki wrote: post #48

I saw a quick flash of unstyled content (in Firefox) where all the text was jammed into one paragraph with no breaks. And then the page rendered normally. So I glanced at the source code, and it surprised me to see that it was not a typical HTML document, but instead an XML document with a stylesheet. It is very rare to see a non-HTML page on the web, whether it is the XHTML serialization of HTML, or fully custom XML…

I agree this is very unusual. It's also somewhat annoying, for example I can't just send this to my Kindle to read it, and I can imagine other tools failing on this as well.

I just tried it on Pocket, and it keeps switching me to the web version... which is a bit frustrating, since the source code / DocBook [1] XML format looks ideal for describing a Pocket article.

Seems DocBook has been around since 1999, judging from when the first O'Reilly book was published about it [2].

I just flagged it with the Pocket app's "Report An Article Display Problem" feature, but it is such a niche use case that I can't imagine them spending time on it.

[1] https://en.wikipedia.org/wiki/DocBook

[2] https://www.oreilly.com/openbook/docbook/book/docbook.html

Re: How to Design Software Good

#72

Post by anonytrary »

GuiA wrote: post #64
anonytrary wrote: post #60

Earlier quoted context omitted.

> By referring to “the user” as “he”, you’re already distracting roughly 50% of your potential readership (if you’re writing the documentation for a Do It Yourself Vasectomy Kit, perhaps you get a pass). Do you have any research/data to back this up? I'm a male and I am not distracted when people use "she" (or "he" for that matter). I have never heard anyone in person complain about not being able to focus on an arti…

There is a user, they are using the system, and that’s about as much as we know about them.

"He" clocks in at two characters, it's a very concise way of referring to an arbitrary person. "The user" takes longer to write and longer to say. Forcing the reader to juggle around "or" conditions (i.e. with "he or she") is even worse and I consider it bad practice. Your readers will thank you for concreteness and brevity.

Re: How to Design Software Good

#73

Post by adrianN »

bkmartin wrote: post #44
fao_ wrote: post #40

Earlier quoted context omitted.

I kind of feel that you just read the title here. It's not talking about the 'fullest': An example of this would be if a music composition program has an easily-reached maximum song size because the code monkey who wrote it used a 16-bit variable instead of a 32-bit one. *While there are sometimes limitations that cannot be overcome*, the actual code written and the architecture used when it was written should have a…

The most common example I see is the password requirement that it must be between 8 and 16 characters... The 16 character limit is the main issue there... You know it has to do with the wya the data is stored.

Between 8 and 16 characters, but only 7 bit ASCII. But there is no error message if you use § in your password, it just kills the server.

Re: How to Design Software Good

#74

Post by [deleted] »

mafro wrote: post #57
nayuki wrote: post #48

I saw a quick flash of unstyled content (in Firefox) where all the text was jammed into one paragraph with no breaks. And then the page rendered normally. So I glanced at the source code, and it surprised me to see that it was not a typical HTML document, but instead an XML document with a stylesheet. It is very rare to see a non-HTML page on the web, whether it is the XHTML serialization of HTML, or fully custom XML…

Once upon a time, the whole internet was going to be built this way!

[deleted]

Re: How to Design Software Good

#75

Post by deaddodo »

chipotle_coyote wrote: post #70
timClicks wrote: post #61

Earlier quoted context omitted.

Which is more the fault of the Kindle than the authors. It's Docbook, a standard that was invented for the purpose of writing books.

It's great to use DocBook for writing books! (Actually, I don't think this is true for most books, but you do you.) But I would argue that processors that are designed to take HTML as input are not at fault for failing to process non-HTML documents. (Many, but not all) web browsers can render and style XML like this, but I'd argue that this is -- somewhat ironically given the article's subject -- probably not the bes…

The only way to build a fully conformant browser is to support rendering HTML as SGML with a DTD. Toy/specialty renderers skip over that step since you can assume 99.9999% of web documents will be HTML. However, they would completely fall apart on standard SGML, styled XML, etc.

Re: How to Design Software Good

#76

Post by chipotle_coyote »

anonytrary wrote: post #54
waddlesplash wrote: post #23

Earlier quoted context omitted.

This document was mostly written almost a decade ago, and by someone who I think went to a prestigious institution. So the "rules of style" back then aren't what they are today. You're right, we should update it, though.

> You're right, we should update it, though. No, you really shouldn't, it's not a real problem. The only people who keep tallies of gender pronouns in documents are internet trolls; don't indulge the trolls. Anyway, switching up pronouns every other time breaks continuity and makes documents harder and painful to read.

The only people who consider switching between "he" and "she" in different examples are internet trolls. Obviously, that's not really true, but neither is your snark.

Look: gender-neutral language in technical writing is not that difficult. Most of the time you can rewrite sentences to simply avoid gendered pronouns, e.g., "the successful applicant will use his skills to contribute to the platform team" becomes "the successful applicant's skills will contribute to the platform team."

As for alternating between pronouns, do you think readers are bothered by switching between using male and female names in examples? If you realize that the first example used Bob, the second used Agatha, and the third used William, do you suddenly leap up, scream INTERNET TROLLS GOT TO THEM!, and punch your monitor? No, probably not. So do you do if you see pronouns switching? Really? Again: I'm betting probably not.

I can tell you that as someone who's done technical writing for a half-dozen companies over the last decade or so that I have never heard of readers complaining about alternating pronouns. I have heard of them complaining about documentation that is exclusively male, though, because it turns out that's something some -- not all, maybe not most, but definitely some -- readers will notice and be a little nonplussed by.

Re: How to Design Software Good

#77

Post by hitsthings »

reificator wrote: post #67
bkmartin wrote: post #44

Earlier quoted context omitted.

The most common example I see is the password requirement that it must be between 8 and 16 characters... The 16 character limit is the main issue there... You know it has to do with the wya the data is stored.

It had better not...

And yet...

Re: How to Design Software Good

#78

Post by cpeterso »

nayuki wrote: post #48

I saw a quick flash of unstyled content (in Firefox) where all the text was jammed into one paragraph with no breaks. And then the page rendered normally. So I glanced at the source code, and it surprised me to see that it was not a typical HTML document, but instead an XML document with a stylesheet. It is very rare to see a non-HTML page on the web, whether it is the XHTML serialization of HTML, or fully custom XML…

Thanks for reporting this problem! I filed a Firefox bug:

https://bugzilla.mozilla.org/show_bug.cgi?id=1506038

This bug is actually a regression in Firefox 58 from the fix for a use-after-free bug (CVE-2018-5097):

https://bugzilla.mozilla.org/show_bug.cgi?id=1387427

Re: How to Design Software Good

#79

Post by bjoli »

mafro wrote: post #57
nayuki wrote: post #48

I saw a quick flash of unstyled content (in Firefox) where all the text was jammed into one paragraph with no breaks. And then the page rendered normally. So I glanced at the source code, and it surprised me to see that it was not a typical HTML document, but instead an XML document with a stylesheet. It is very rare to see a non-HTML page on the web, whether it is the XHTML serialization of HTML, or fully custom XML…

Once upon a time, the whole internet was going to be built this way!

I still think client side XSLT is a good thing. I write simple documents and it is automatically converted client side. The world's best static site generator.

I gives me the best of two worlds: simple markup with complete control of output and CSS styling and instant changes of all documents without a compilation step.

Re: How to Design Software Good

#80

Post by CathyWest »

> Writing good software can be hard, but it is worth the time and effort.

Is it? I want this to be true because I want to write good software. But I've worked with some very senior developers who would disregard all software engineering and user experience concerns and just spew large quantities of low-quality code that made the managers just as happy, especially since it got done quickly. And the end-users in many niche industries are used to being shipped garbage, so they're just as happy too.

Post reply on HN