yaobinwen / document-shredded Goto Github PK
View Code? Open in Web Editor NEWPromote documentation best practices
Home Page: https://yaobinwen.github.io/document-shredded/
License: MIT License
Promote documentation best practices
Home Page: https://yaobinwen.github.io/document-shredded/
License: MIT License
Very immature idea but basically:
amixer
documentation may not be good enough. Take this question for example:
Why do we supply
pulse
as a parameter inamixer
command?I have noticed if I doesn't supplypulse
parameter toamixer
command it doesn't work and throws error.
However, the owner of the answer didn't reply it. I have the same question. Unfortunately, I don't seem to be able to find the answer with some quick search (e.g., amixer(1)
).
Another question is: What is the Master
control in amixer
? There doesn't seem to be an answer about that. amixer(1)
has an example that says:
amixer -c 1 -- sset Master playback -20dB
will set the master volume of the second card to -20dB. If the master has multiple channels, all channels are set to the same value.
which seems to suggest that Master
is a special control that covers all the available "channels".
The article A close look at ALSA has a section "ALSA concepts" which explains "cards" and "devices", but it doesn't explain what the Master
is.
Anyway, I think many open source projects need to build better documentation in order to transfer knowledge.
An Ansible issue: Documentation: Add warnings about using facts based hostvars['hostname']
.
Ansible subelements
documentation is not so clear:
0
and 1
come from.2
or even more.I may write a book for beginners to learn programming in a general sense, not about a specific language.
Then once the beginner gets some experience, he/she no longer needs to read a book as fluffy as The Go Programming Language. He/she should be able to grab the language reference or cheat sheet to learn the language quickly.
The Go Programming Language sins:
I don't know how DDD can relate to this project but there might be some intrinsic connection between them because they are both about documentation:
Goals of good documentation:
Good documentation should include:
Good documentation tells EVERYTHING about the software. However, this is almost impossible because chances are the developers themselves do not have a total grasp on the software: it's just too complex.
CMake 3.21.3 tutorial does not provide a link to the accompanying source code, or at least the link is very difficult to find unless I search it in Google (and the repository is not even the top results in Google search results). However, the tutorial itself refers to the code frequently and makes me frustrated not to be able to read the code while reading the tutorial.
FYI: The code is here.
Today (2021-05-04) I tried to learn about "Heuristic Freshness Checking". This page refers to RFC 7234 Section 4.2.2, but I find this section doesn't provide any specific example so it's hard to understand how it is calculated by simply reading the text.
Some other references I can take a look:
Doc smell: infinite links which means one resource provides a link to another resource which provides a link to a further resource but none of them explain the things clearly enough.
See this Stack Overflow question and one of the comments.
Actually, it turned out to be that React Router v6 is quite different from the earlier versions and they published the documentation for v6 here. Technically, they didn't do anything wrong. However, they probably should have mentioned in the documentation website that v6 is quite different so the users should pay attention to the version they are using.
Coding Horror: If It Isn't Documented, It Doesn't Exist
In another article, Learn to Read the Source, Luke, the author said:
And because writing for people is way harder than writing for machines, the documentation will continue to suck for the forseeable future. There's very little you can do about it.
Well, the document-shredded
project aims to improving this.
Vagrant CLI documentation is not so clear.
The action plugins are run in the context of the user that launches the playbook so it is not affected by --become
. Is this documented anywhere?
#ansible
channel.This issue collects the cases of "loss of knowledge": Because programmers come and go, when a project has been ongoing for quite a long time, the knowledge of some part of the code may get lost along the way.
It needs further evaluation to see if this is caused by lack of good documentation, but usually that means the implemented feature is not important in practice so nobody really cares.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.