The author argues that man pages themselves are a valuable and well-structured source of information, contrary to popular complaints. The problem, they contend, lies with the default man reader, which uses less, hindering navigation and readability. They suggest alternatives like mandoc with a pager like less -R or specialized man page viewers for a better experience. Ultimately, the author champions the efficient and comprehensive nature of man pages when presented effectively, highlighting their consistent organization and advocating for improved tooling to access them.
To write blog posts that developers will actually read, focus on providing clear, concise, and practical information. Prioritize code examples, concrete solutions, and a logical flow that mirrors the developer's problem-solving process. Avoid unnecessary jargon, flowery language, and long introductions. Instead, get straight to the point, explain the "why" behind the "how," and use visuals like diagrams and screenshots to illustrate complex concepts. Finally, ensure your code is functional, well-formatted, and easily testable by readers. This approach respects the developer's time and provides immediate value, making your blog post a useful resource they'll appreciate and share.
HN commenters generally praised the article for its practical advice on writing for a technical audience. Several highlighted the importance of clarity, conciseness, and providing concrete examples, echoing the article's points. Some suggested additional tips, like linking to relevant resources and using clear diagrams. One commenter appreciated the focus on empathy for the reader and understanding their context. A few debated the value of analogies, with some finding them helpful while others considered them distracting or potentially misleading. The emphasis on respecting the reader's time and intelligence was a recurring theme throughout the comments.
Steve Losh's "Teach, Don't Tell" advocates for a more effective approach to conveying technical information, particularly in programming tutorials. Instead of simply listing steps ("telling"), he encourages explaining the why behind each action, empowering learners to adapt and solve future problems independently. This involves revealing the author's thought process, exploring alternative approaches, and highlighting potential pitfalls. By focusing on the underlying principles and rationale, tutorials become less about rote memorization and more about fostering genuine understanding and problem-solving skills.
Hacker News users generally agreed with the "teach, don't tell" philosophy for giving feedback, particularly in programming. Several commenters shared anecdotes about its effectiveness in mentoring and code reviews, highlighting the benefits of guiding someone to a solution rather than simply providing it. Some discussed the importance of patience and understanding the learner's perspective. One compelling comment pointed out the subtle difference between explaining how to do something versus why it should be done a certain way, emphasizing the latter as key to fostering true understanding. Another cautioned against taking the principle to an extreme, noting that sometimes directly telling is the most efficient approach. A few commenters also appreciated the article's emphasis on avoiding assumptions about the learner's knowledge.
While implementing algorithms from Donald Knuth's "The Art of Computer Programming" (TAOCP), the author uncovered a few discrepancies. One involved an incorrect formula for calculating index values in a tree-like structure, leading to crashes when implemented directly. Another error related to the analysis of an algorithm's performance, where a specific case was overlooked, potentially impacting the efficiency calculations. The author reported these findings to Knuth, who confirmed the issues and issued corrections, highlighting the ongoing evolution and collaborative nature of perfecting even such a revered work. The experience underscores the value of practical implementation in verifying theoretical computer science concepts.
Hacker News commenters generally express admiration for both Knuth and the detailed errata-finding process described in the linked article. Several discuss the value of meticulous proofreading and the inevitability of errors, even in highly regarded works like The Art of Computer Programming. Some commenters point out the impressive depth of analysis involved in uncovering these errors, noting the specialized knowledge and effort required. A few lament the declining emphasis on rigorous proofreading in modern publishing, contrasting it with Knuth's dedication to accuracy and his reward system for finding errors. The overall tone is one of respect for Knuth's work and appreciation for the effort put into maintaining its quality.
Promptless, a YC W25 startup, has launched a service to automatically update customer-facing documentation. It connects to internal tools like Jira, Github, and Slack, monitoring for changes relevant to documentation. When changes are detected, Promptless uses AI to draft updates and suggests them to documentation writers for review and approval before publishing. This eliminates the manual process of tracking changes and updating docs, ensuring accuracy and reducing stale information for improved customer experience.
The Hacker News comments express skepticism about Promptless's value proposition. Several commenters question the need for AI-driven documentation updates, arguing that good documentation practices already involve regular reviews and updates. Some suggest that AI might introduce inaccuracies or hallucinations, making human oversight still crucial and potentially negating the time-saving benefits. Others express concern about the "black box" nature of AI-driven updates and the potential loss of control over messaging and tone. A few commenters find the idea interesting but remain unconvinced of its practical application, especially for complex or nuanced documentation. There's also discussion about the limited use cases and the potential for the tool to become just another layer of complexity in the documentation workflow.
This post advocates for clear, legible mathematical handwriting, emphasizing the importance of distinguishing similar symbols. It offers specific guidelines for writing letters (like lowercase 'x' and 'times,' 'u' and 'union,' and Greek letters), numerals (particularly distinguishing '1,' '7,' and 'I'), and other mathematical symbols (such as plus/minus, radicals, and various brackets). The author stresses vertical alignment within equations, proper spacing, and the use of serifs for improved clarity. Overall, the goal is to enhance readability and avoid ambiguity in handwritten mathematics, benefiting both the writer and anyone reading the work.
Hacker News users discuss the linked guide on mathematical handwriting, largely praising its practical advice. Several commenters highlight the importance of clear communication in mathematics, emphasizing that legible handwriting benefits both the writer and the reader. Some share personal anecdotes about struggling with handwriting and the impact it has on mathematical work. The suggestion to practice writing Greek letters resonates with many, as does the advice on spacing and distinguishing similar-looking symbols. A few commenters offer additional tips, such as using lined paper turned sideways for better vertical alignment and practicing writing on a whiteboard to improve clarity and flow. Overall, the comments reflect an appreciation for the guide's focus on the often-overlooked skill of legible mathematical writing.
After 75 years, the Society for Technical Communication (STC) is permanently closing, effective July 15, 2024. Facing declining membership and revenue, the organization's Board of Directors determined it could no longer sustain operations. STC will cease all activities, including its annual summit, publications, and certification programs. The organization expressed gratitude for its members and their contributions to the field of technical communication.
HN commenters lament the closure of the Society for Technical Communication (STC), expressing surprise and sadness at the loss of a long-standing organization. Several speculate on the reasons for the closure, citing declining membership, the rise of free online resources, and the changing nature of technical communication. Some question the STC's relevance in the modern landscape, while others highlight its historical importance and the valuable resources it provided. A few commenters express hope that another organization will fill the void left by the STC, preserving its archives and continuing its mission of advancing the field of technical communication. Some users discuss their personal positive experiences with the organization. One notes a large amount of student debt held by the organization.
Summary of Comments ( 63 )
https://news.ycombinator.com/item?id=43631672
HN commenters largely agree with the author's premise that man pages are a valuable resource, but the tools for accessing them are often clunky. Several commenters point to the difficulty of navigating long man pages, especially on mobile devices or when searching for specific flags or options. Suggestions for improvement include better search functionality within man pages, more concise summaries at the beginning, and alternative formatting like collapsible sections.
tldrandcheatare frequently mentioned as useful alternatives for quick reference. Some disagree, arguing that man pages' inherent structure, while sometimes verbose, makes them comprehensive and adaptable to different output formats. Others suggest the problem lies with discoverability, and tools likeaproposshould be highlighted more. A few commenters even advocate for generating man pages automatically from source code docstrings.The Hacker News post titled "Man pages are great, man readers are the problem" (linking to an article of the same name) generated a substantial discussion with diverse opinions. Several commenters agreed with the article's premise, citing the density and comprehensive nature of man pages as strengths, and pointing to the awkwardness of
man's default pager,less, as a major usability hurdle. They suggest alternative pagers likebator incorporating search functionalities within the pager as improvements. One commenter specifically praised the use oftldrpages for quicker access to common usage examples, while acknowledging man pages as the ultimate source of truth. Another commenter noted how valuable the full technical specifications and corner cases documented in man pages are, even if they are not needed for everyday usage. The verbosity and occasional outdatedness of man pages were mentioned as minor drawbacks, though not significant enough to detract from their overall value.Some commenters argued against the article's premise. They expressed frustration with the structure of man pages, finding the information organization illogical and difficult to navigate, even with improved pagers. They criticized the lack of consistency across different man pages, making it challenging to predict where specific information might be located. These commenters often suggested alternative documentation formats like web pages or dedicated documentation sites, which they perceived as being more user-friendly. One commenter pointed out that the author's preferred approach using
man -Tpdfand a PDF viewer was a workaround rather than a solution to the underlying usability issues withman.A few commenters took a more nuanced approach, acknowledging the strengths of man pages while also recognizing their shortcomings. They proposed improvements such as better indexing and search capabilities, more consistent formatting, and perhaps even incorporating some of the strengths of alternative documentation styles into man pages themselves. One commenter highlighted the importance of context and how man pages, being primarily designed for command-line use, fit well within that specific context. They also pointed to the benefit of man pages being readily available offline, a crucial advantage in certain situations. There was also some discussion about the learning curve associated with using man pages effectively, with some users appreciating the challenge while others found it unnecessarily steep.
Finally, there were a few tangential comments, including one about the history of Unix documentation and the cultural significance of man pages. Another commenter questioned the value of man pages in the modern software development landscape, arguing that many modern tools and libraries often lack adequate man page documentation. Overall, the comment section reflects a wide range of opinions on the utility and usability of man pages, with a general agreement that improvements are needed but disagreement on the best approach to achieve them.