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