Follow Tom's Hardware on Google News , or add us as a preferred source , to get our latest news, analysis, & reviews in your feeds.
Bruno Ferreira Contributor Bruno Ferreira is a contributing writer for Tom's Hardware. He has decades of experience with PC hardware and assorted sundries, alongside a career as a developer. He's obsessed with detail and has a tendency to ramble on the topics he loves. When not doing that, he's usually playing games, or at live music shows and festivals.
-Fran- It's important to make this distinction: code being "clean" (readable, maintainable and beautiful) is not the same has having documentation at the functionality/higher level. The code is not user documentation! This phrasing is mostly for comments and other in-line helps: if you need to explain it, then it's not clear enough (readable or maintainable). I'm not an extremist when it comes to comments, as sometimes decisions/approaches need an explanation (outside of immediate code scope context) so it's not changed in a way which would break things. Whenever a developer gives me the "my code is good, so I don't need to document it", I send them to the Gulag. Regards. Reply
-Fran- ezst036 said: The man pages are not really user documentation either, they're "techie" documentation and usually for more-techie-than-average techies at that. The man pages ARE user documentation as they document USAGE . Anything that tells you how to interact or USE a piece of software is "user documentation". Anything that talks design or even "code", then it's a design/architectural document. I don't even want to go down that rabbit hole, since there's several different approaches there and ways to accomplish the same end-goal: explain how things are built and maintained. You can use any other internal labels you want, but at the most fundamental level, it's just "user documentation". Documentation, in the broader sense, has many different facets and your target audience defines both the content and writing style. So I half agree with your semantic distinction to call the man pages "techie user documentation", but never forget they are still "user" level documentation for a very specific target audience. Regards. Reply
qxp Just want to add to the article that the filesystem mount API discussed is a C API, meant to be used by developers writing programs that need to mount or unmount filesystems. These are not commands used in a terminal. Thus I think it is perfectly OK that the developers of system level tools needed to read the implementation code or messages from API developers to find out how to properly use the API. And now that its been used for some time and stabilized it is being documented. Reply
Sam Hobbs ezst036 said: The man pages are not really user documentation either, they're "techie" documentation and usually for more-techie-than-average techies at that. IBM documentation tends to consist of both a reference and a user guide. The user guide is intended for beginners and others that want an easier explanation and do not need the details. The reference is more technical. I think that if I had a choice of one or the other, I would choose a reference. It is possible to write a user guide from a reference but it is not possible to write a reference from a user guide. I think it is important that the man page documentation include all technical details necessary for the use of the software. Other (educational) documentation could be developed from that. ezst036 said: From no man to man to YouTube. I think you misunderstand what documentation is. YouTube is great for tutorials but useless for documentation. Now with AI it is possible for an AI system to analyze source code and create specifications. Documentation is much like specifications; the documentation could be developed from the specifications. Also, it is hopefully easier to read specifications than the source code. This might be an excellent opportunity to explore such solutions. The following is what Perplexity AI says on the subject. https://www.perplexity.ai/search/i-read-an-article-saying-that-SntxdNRaR.WqUlBeldUdug#0 Reply
Key considerations
- Investor positioning can change fast
- Volatility remains possible near catalysts
- Macro rates and liquidity can dominate flows
Reference reading
- https://www.tomshardware.com/software/linux/SPONSORED_LINK_URL
- https://www.tomshardware.com/software/linux/linuxs-contemporary-filesystem-mount-api-went-without-documentation-for-six-years-latest-man-page-package-finally-adds-content-for-2019-code#main
- https://www.tomshardware.com
- Chinese memory maker CXMT prepares $4.2 billion USD IPO to take advantage of tight memory market — company lays out path to profitability as DRAM demand skyrock
- Nvidia's CUDA Tile examined: AI giant releases programming style for Rubin, Feynman, and beyond — tensor-native execution model lays the foundation for Blackwel
- Grab this 4K gaming PC with an RTX 5080 and 9800X3D for just $2,499 before prices skyrocket — $200 saving on powerful Skytech rig with 32GB of DDR5 RAM and 1TB
- 3 Ways NVIDIA Is Powering the Industrial Revolution
- SoftBank stakes $4B on securing AI data center power and capacity — DigitalBridge purchase indicative of AI industry's increasing investments in energy supply
Informational only. No financial advice. Do your own research.