List of technical documentation: is it a useful page? What should be here? What should not?
Michael Shiloh
michael at openmoko.org
Mon Aug 25 23:36:45 CEST 2008
Hello kind documentation team,
While searching for the list of /sys files I stumbled onto
http://wiki.openmoko.org/wiki/List_of_technical_documentations,
described as:
"On this page, you can find technical documentations , including how to
use bluetooth, GPS....etc, contributes from community.
I took it upon myself to reword this to correct the grammar and to
provide a more meaningful description.
However, looking over the list of links, it strikes me that pretty much
everything on the wiki is in fact technical documentation. True, there
are clear exceptions, but does it really make sense to have a page that
is essentially the same as the index?
My big concern is this: If there are multiple sources of information,
there is an excellent chance that they will be out of sync, leading to
confusion.
Furthermore, this page requires that an author manually insert their
document into this page, increasing the chance that an excellent
technical document will in fact not be listed here. (Case in point: The
list of /sys files that I was seeking is in fact not here!)
So I propose we get rid of this page. Perhaps a more useful way to
identify technical documents would be to have a category, but that too
requires manually setting the category correctly, and so is prone to
failure.
The only use I can see for this page is to collect links to _external_
documents, but then I would name it as such.
Discussion?
More information about the documentation
mailing list