Broken documentation
Respectfully, the documentation for this project is broken.
I am very close to having a working image to use on an Asterisk phone system.
The idea is to have no moving parts in the server (other than 1 cooling fan in the power supply).
It boots from a compact flash card in a USB reader. I think I might have it write to a separate SD card or to a MySQL server for call records and voice messages , have not decided yet. I'd like it to continue working independent of the status of the rest of the network.
I'm frustrated when I hit a problem in Debian Live and I turn to the docs for help.
As a beginner I don't want to bring up what seem like obvious problems that everyone must have on a mailing list, it clogs the list and takes too long to get useful feedback.
When I refer to the Debian Live manual for help, what I most often see is
"FIXME"
But fortunately there is a wiki, so I turn to it! When I go there I see this:
"Please do not add new content to the wiki, but contribute to the manual directly."
Well, I am not able to contribute yet to a manual, I just need a little help. But say I wanted to take a stab at filling in one of those FIXME's. I can't do that, instead when I follow the contribute link I see this
"The preferred way to submit a contribution is to send it to the mailing list."
SO the feedback loop is very open - I submit something and someone anonymous somewhere someday might possibly consider whether my submission is good enough and add it. Then maybe someday it will show up on the site.
I can't figure out how Debian Live is supposed to work so I am not inclined yet to write up formal documents, and I can't make informal contributions to a wiki to collaborate on a more complete manual and help others. None of the docs have improved in the year or so I have been looking at them, so I am not inclined to try the formal submission approach (I can see that it's not working).
I still don't know how things are supposed to work, and I think a basic overview should either be in the wiki or the manual.
My specific problem: when I change a file, and it does not show up in the finished image, I get very annoyed and frustrated. The instance I am talking about right now is the /etc/network/interfaces file. I put it into config/ tree, I put it into chroot/ tree and still it seems to end up with my changes ignored. What is in the finished image is generic and does not even have my interfaces in it.
So some step overwrites my changes before they go from chroot/ into the finished binary image. Where? How do I fix this?
The options should not be (a) figure it or (b) write to a mailing list.
My big suggestion is this:
Locked down manuals are obsolete. Scrap it and free the wiki.
Brian
Reply to: