8 ms·

Redesigned GNU C Library manual

104 points by elmerland 12y ago

DanBC 12y ago
These types of comment are now officially off-topic so I wouldn't normally make them but, since this submission is about the design of the webpage: http://imgur.com/NNmmxdx http://imgur.com/NNmmxdx http://imgur.com/qv6BPj4 http://imgur.com/qv6BPj4 This is latest Chrome on iOS. That header banner is fixed (that's sub-optimal) and all the content is in that little box.
- elmerland 12y ago
  Yeah I agree with your comments. Initially I only tested as far down as tablets, because I figured that the target audience are programmers on their laptops or desktops. I will be fixing this issue on the next iteration.
- aw3c2 12y ago
  As someone who often makes these comments, were they declared offtopic somewhere official?
  - DanBC 12y ago
    Here's a comment from dang. Someone made a good, technical, submission. For a while the highest comment was about the design of the blog. https://news.ycombinator.com/item?id=9238739 https://news.ycombinator.com/item?id=9238739 > A reader emailed to complain about how this and other HN discussions often become derailed by off-topic carping about blog design. I agree completely. Could there be a more classic form of bikeshedding? It would seem parodic if it weren't sadly real. This has become more of a thing on HN lately. It needs to become less of a thing. > I don't mean to pick on you personally, or just on this one comment. (Your second sentence alone, by the way, would have been a helpful contribution.) The problem is the tedious stampedes such comments spawn. This submission is a bit different because the design of the page is the thing being submitted, but I'm aware that I too easily make comments about the design of the page rather than the content of the page. Some design choices are weird and prevent people from being able read the content and I wish there was a way to provide that feedback without derailing a thread.
    - aw3c2 12y ago
      Aye, that was my comment. :) I hope HN will come up with a nice solution to allow these kinds of comments but have them be less distracting.
      - krapp 12y ago
        Arguably, a threaded forum by design encourages tangential discussions which deviate from the topic the deeper you go. The problem in HN's case is all the threads are open and entirely visible - which is one of the cases where its minimalist layout works against readability. I think the best solution would be thread folding (which I know is being worked on anyway) where the default is that all threads are collapsed. Then, off topic discussion wouldn't take up any more than a single post's worth of space by default. Having it be a conscious choice to move deeper into a thread also ensures that no one has to scroll past much content they don't care about.
        aw3c2 12y ago
        That would be incredibly annoying on touch interfaces and generally not allow quick scanning of comments anymore. It would take a lot more time.
        krapp 12y ago
        I suppose open threads by default would be more friendly, or maybe defaulting to open for mobile layouts. But it taking more time would kind of be the point - opting in to participate rather than opting out by scrolling past content means fewer sarcastic comments about how a thread is off topic and irrelevant.
    - Dewie 12y ago
      "Bikeshedding" has become yet another empty dismissal. The colour of a bikeshed is irrelevant when designing a nuclear reactor. But the "bikeshed" of a webpage has to do with usability, which is a critical component of any webpage.
pekk 12y ago
Unless I've missed something, this isn't a redesign of the library, it's a restyling of the manual as a website.
- elmerland 12y ago
  You are correct, this is just a restyling of the manual. Just curious, what did you think 'redesign' meant? I have mostly a front end background and I thought I was using the word correctly. But I might have been wrong.
  - samatman 12y ago
    Redesigning the GNU C Library would be, well, redesigning the GNU C Library. What you've done is redesign the GNU C Library manual, HTML edition. Which you have done well, IMHO. It doesn't seem to involve refactoring C code.
  - jnazario 12y ago
    from the phrasing i would have expected the code itself had been changed.
- elmerland 12y ago
  That makes sense, I have changed the title. Thanks for pointing it out!
  - a1369209993 12y ago
    > Redesigned GNU C Library manual Its still readable as "manual for a redesigned GNU C library" in addition to the presumably intended "redesigned manual for the GNU C library".
dman 12y ago
Could you get the sections to start out expanded by default?
- JonathonW 12y ago
  Agreed on this. An Expand All/Collapse All button would also be nice (but not instead of expanding by default-- the whole reason I'd be reading those documents is to read the stuff in the collapsed sections).
- coyotebush 12y ago
  Agreed that the expandable sections feel a little unusual for this type of documentation. They're great for drilling down to particular information, but not so much for skimming or reading straight through. I might even suggest putting the sub-section navigation in the sidebar a la readthedocs.
- elmerland 12y ago
  Yeah I could definitely do this. If I were to add a collapse/expand all button would you still prefer for all the sub-sections to be expanded by default?
  - dman 12y ago
    Yes I think so, the pane on the left already allows the user to control which section they are reading. I would assume that once a reader is in a section they would likely want to read/scan all of it. Excellent work by the way!
- ausjke 12y ago
  Agreed, it's tedious to click on each item to expand the page. Either expand it by default or provide a global switch for that expandability.
kasabali 12y ago
It looks great! I haven't inspected how you did it but I guess it shouldn't be hard to apply it to other GNU manuals also, as all are very similar in the sense that they all are produced using the same tools. Another idea: local search function similar to Sphinx's would be really nice.
- elmerland 12y ago
  Thats a great idea! This project was somewhat of a proof of concept. Maybe I will refine and apply it to other manual. Thanks! PS: I couldn't find the local search function that you mentioned. Can you put a link so that I can see how it works?
  - deleted 12y ago
    [deleted]
  - kasabali 12y ago
    Sure. Python documentation in https://docs.python.org/3/archives/python-3.4.3-docs-html.zip https://docs.python.org/3/archives/python-3.4.3-docs-html.zi... is a good example. You can extract it anywhere and search just works without needing any server side components.
- kasabali 12y ago
  why is this comment downvoted?
Hello71 12y ago
$ links https://www.gnu.org/software/libc/manual/html_mono/libc.html Link: [start: Top] Link: [index: Concept Index] Link: [contents: Table of Contents] Link: [up: (dir)] The GNU C Library Short Table of Contents * [1 Introduction] * [2 Error Reporting] * [3 Virtual Memory Allocation And Paging] * [4 Character Handling] * [5 String and Array Utilities] * [6 Character Set Handling] * [7 Locales and Internationalization] * [8 Message Translation] * [9 Searching and Sorting] * [10 Pattern Matching] ^C $ links http://elmerland.com/gnu_manual.html The GNU C Library [About] [By: Elmer Landaverde] Edit: Added [] to show selectable links (note that [] are not actually displayed in links' output)
- striking 12y ago
  This is the most graceful CSS-degradation I've ever seen. The world needs to learn from this manual in how to do HTML right. If you haven't tried it yourself you're missing out. It's truly art.
  - jdjb 12y ago
    And yet the whole thing doesn't load if you block javascript. No content at all.
    - cbd1984 12y ago
      So goodbye to accessibility.
      - wirrbel 12y ago
        how does this reduce accessibility? javascript interpreters are not hard to find nowadays.
        easytiger 12y ago
nirvanis 12y ago
On a semi-related note: Man Pages in HTML that do not look ugly: http://linux.bar/man1/memusage.1.html http://linux.bar/man1/memusage.1.html
deleted 12y ago
[deleted]
hurin 12y ago
It really doesn't work for me. Here is why: A big part of manuals is being able to read or scroll fluidly into the next or previous section - very often one doesn't know whether what they are looking for is mentioned in 1.3.1 or 1.3.2 - having to manually click each section is completely atrocious for usability. Not to mention you just broke search. If you want a responsive design that's actually useful as opposed to counterproductive, leave the sidebar for navigation (down-scale it to 50% it's huge and distracting) and restore the document to a contiguous form. There is a reason manuals have been written the way they are for dozens of years, hip and flashy design elements might sell products - but they do not help with productivity.
- detaro 12y ago
  A big part of manuals is being able to read or scroll fluidly into the next or previous section - very often one doesn't know whether what they are looking for is mentioned in 1.3.1 or 1.3.2 - having to manually click each section is completely atrocious for usability. Not to mention you just broke search. This, it is often split in sections smaller than the screen so you have to uncollapse way to many items. Make the navigation jump to the right section in the document, maybe allow to collapse sections, but have it all visible by default.
fit2rule 12y ago
This is a really great resource - so great, I'd love to have an offline copy for reference. However it doesn't look like its set up for easy mirroring with wget .. does anyone else have an idea how it could be mirrored locally for offline use, or shall I just contact the author?
- edwintorok 12y ago
  You can mirror with wget the original, it has the same contents AFAICT, just different CSS: https://news.ycombinator.com/item?id=9245753 https://news.ycombinator.com/item?id=9245753
cplease 12y ago
I have a big problem with this. The header says "The GNU C Library" and then in big letters "By: Elmer Landaverde". You did not write either glibc or the manual. The original authors did not credit themselves, yet you've appropriated credit for what is essentially restyling the HTML output of texinfo into a less usable, unscrollable, unsearchable form. If you insist on the huge attribution, change it to something accurate like "Style template by:"
- elmerland 12y ago
  That's fair.
notdang 12y ago
Doesn't work without javascript

104 points by elmerland 12y ago

DanBC 12y ago

These types of comment are now officially off-topic so I wouldn't normally make them but, since this submission is about the design of the webpage: http://imgur.com/NNmmxdx http://imgur.com/NNmmxdx http://imgur.com/qv6BPj4 http://imgur.com/qv6BPj4 This is latest Chrome on iOS. That header banner is fixed (that's sub-optimal) and all the content is in that little box.

elmerland 12y ago
Yeah I agree with your comments. Initially I only tested as far down as tablets, because I figured that the target audience are programmers on their laptops or desktops. I will be fixing this issue on the next iteration.
aw3c2 12y ago
As someone who often makes these comments, were they declared offtopic somewhere official?
- DanBC 12y ago
  Here's a comment from dang. Someone made a good, technical, submission. For a while the highest comment was about the design of the blog. https://news.ycombinator.com/item?id=9238739 https://news.ycombinator.com/item?id=9238739 > A reader emailed to complain about how this and other HN discussions often become derailed by off-topic carping about blog design. I agree completely. Could there be a more classic form of bikeshedding? It would seem parodic if it weren't sadly real. This has become more of a thing on HN lately. It needs to become less of a thing. > I don't mean to pick on you personally, or just on this one comment. (Your second sentence alone, by the way, would have been a helpful contribution.) The problem is the tedious stampedes such comments spawn. This submission is a bit different because the design of the page is the thing being submitted, but I'm aware that I too easily make comments about the design of the page rather than the content of the page. Some design choices are weird and prevent people from being able read the content and I wish there was a way to provide that feedback without derailing a thread.
  - aw3c2 12y ago
    Aye, that was my comment. :) I hope HN will come up with a nice solution to allow these kinds of comments but have them be less distracting.
    - krapp 12y ago
      Arguably, a threaded forum by design encourages tangential discussions which deviate from the topic the deeper you go. The problem in HN's case is all the threads are open and entirely visible - which is one of the cases where its minimalist layout works against readability. I think the best solution would be thread folding (which I know is being worked on anyway) where the default is that all threads are collapsed. Then, off topic discussion wouldn't take up any more than a single post's worth of space by default. Having it be a conscious choice to move deeper into a thread also ensures that no one has to scroll past much content they don't care about.
      - aw3c2 12y ago
        That would be incredibly annoying on touch interfaces and generally not allow quick scanning of comments anymore. It would take a lot more time.
        krapp 12y ago
        I suppose open threads by default would be more friendly, or maybe defaulting to open for mobile layouts. But it taking more time would kind of be the point - opting in to participate rather than opting out by scrolling past content means fewer sarcastic comments about how a thread is off topic and irrelevant.
  - Dewie 12y ago
    "Bikeshedding" has become yet another empty dismissal. The colour of a bikeshed is irrelevant when designing a nuclear reactor. But the "bikeshed" of a webpage has to do with usability, which is a critical component of any webpage.

pekk 12y ago

Unless I've missed something, this isn't a redesign of the library, it's a restyling of the manual as a website.

elmerland 12y ago
You are correct, this is just a restyling of the manual. Just curious, what did you think 'redesign' meant? I have mostly a front end background and I thought I was using the word correctly. But I might have been wrong.
- samatman 12y ago
  Redesigning the GNU C Library would be, well, redesigning the GNU C Library. What you've done is redesign the GNU C Library manual, HTML edition. Which you have done well, IMHO. It doesn't seem to involve refactoring C code.
- jnazario 12y ago
  from the phrasing i would have expected the code itself had been changed.
elmerland 12y ago
That makes sense, I have changed the title. Thanks for pointing it out!
- a1369209993 12y ago
  > Redesigned GNU C Library manual Its still readable as "manual for a redesigned GNU C library" in addition to the presumably intended "redesigned manual for the GNU C library".

dman 12y ago

Could you get the sections to start out expanded by default?

JonathonW 12y ago
Agreed on this. An Expand All/Collapse All button would also be nice (but not instead of expanding by default-- the whole reason I'd be reading those documents is to read the stuff in the collapsed sections).
coyotebush 12y ago
Agreed that the expandable sections feel a little unusual for this type of documentation. They're great for drilling down to particular information, but not so much for skimming or reading straight through. I might even suggest putting the sub-section navigation in the sidebar a la readthedocs.
elmerland 12y ago
Yeah I could definitely do this. If I were to add a collapse/expand all button would you still prefer for all the sub-sections to be expanded by default?
- dman 12y ago
  Yes I think so, the pane on the left already allows the user to control which section they are reading. I would assume that once a reader is in a section they would likely want to read/scan all of it. Excellent work by the way!
ausjke 12y ago
Agreed, it's tedious to click on each item to expand the page. Either expand it by default or provide a global switch for that expandability.

kasabali 12y ago

It looks great! I haven't inspected how you did it but I guess it shouldn't be hard to apply it to other GNU manuals also, as all are very similar in the sense that they all are produced using the same tools. Another idea: local search function similar to Sphinx's would be really nice.

elmerland 12y ago
Thats a great idea! This project was somewhat of a proof of concept. Maybe I will refine and apply it to other manual. Thanks! PS: I couldn't find the local search function that you mentioned. Can you put a link so that I can see how it works?
- deleted 12y ago
  [deleted]
- kasabali 12y ago
  Sure. Python documentation in https://docs.python.org/3/archives/python-3.4.3-docs-html.zip https://docs.python.org/3/archives/python-3.4.3-docs-html.zi... is a good example. You can extract it anywhere and search just works without needing any server side components.
kasabali 12y ago
why is this comment downvoted?

Hello71 12y ago

$ links https://www.gnu.org/software/libc/manual/html_mono/libc.html Link: [start: Top] Link: [index: Concept Index] Link: [contents: Table of Contents] Link: [up: (dir)] The GNU C Library Short Table of Contents * [1 Introduction] * [2 Error Reporting] * [3 Virtual Memory Allocation And Paging] * [4 Character Handling] * [5 String and Array Utilities] * [6 Character Set Handling] * [7 Locales and Internationalization] * [8 Message Translation] * [9 Searching and Sorting] * [10 Pattern Matching] ^C $ links http://elmerland.com/gnu_manual.html The GNU C Library [About] [By: Elmer Landaverde] Edit: Added [] to show selectable links (note that [] are not actually displayed in links' output)

striking 12y ago
This is the most graceful CSS-degradation I've ever seen. The world needs to learn from this manual in how to do HTML right. If you haven't tried it yourself you're missing out. It's truly art.
- jdjb 12y ago
  And yet the whole thing doesn't load if you block javascript. No content at all.
  - cbd1984 12y ago
    So goodbye to accessibility.
    - wirrbel 12y ago
      how does this reduce accessibility? javascript interpreters are not hard to find nowadays.
      - easytiger 12y ago

nirvanis 12y ago

On a semi-related note: Man Pages in HTML that do not look ugly: http://linux.bar/man1/memusage.1.html http://linux.bar/man1/memusage.1.html

deleted 12y ago

[deleted]

hurin 12y ago

It really doesn't work for me. Here is why: A big part of manuals is being able to read or scroll fluidly into the next or previous section - very often one doesn't know whether what they are looking for is mentioned in 1.3.1 or 1.3.2 - having to manually click each section is completely atrocious for usability. Not to mention you just broke search. If you want a responsive design that's actually useful as opposed to counterproductive, leave the sidebar for navigation (down-scale it to 50% it's huge and distracting) and restore the document to a contiguous form. There is a reason manuals have been written the way they are for dozens of years, hip and flashy design elements might sell products - but they do not help with productivity.

detaro 12y ago
A big part of manuals is being able to read or scroll fluidly into the next or previous section - very often one doesn't know whether what they are looking for is mentioned in 1.3.1 or 1.3.2 - having to manually click each section is completely atrocious for usability. Not to mention you just broke search. This, it is often split in sections smaller than the screen so you have to uncollapse way to many items. Make the navigation jump to the right section in the document, maybe allow to collapse sections, but have it all visible by default.

fit2rule 12y ago

This is a really great resource - so great, I'd love to have an offline copy for reference. However it doesn't look like its set up for easy mirroring with wget .. does anyone else have an idea how it could be mirrored locally for offline use, or shall I just contact the author?

edwintorok 12y ago
You can mirror with wget the original, it has the same contents AFAICT, just different CSS: https://news.ycombinator.com/item?id=9245753 https://news.ycombinator.com/item?id=9245753

cplease 12y ago

I have a big problem with this. The header says "The GNU C Library" and then in big letters "By: Elmer Landaverde". You did not write either glibc or the manual. The original authors did not credit themselves, yet you've appropriated credit for what is essentially restyling the HTML output of texinfo into a less usable, unscrollable, unsearchable form. If you insist on the huge attribution, change it to something accurate like "Style template by:"

elmerland 12y ago
That's fair.

notdang 12y ago

Doesn't work without javascript