Ya que yo soy el único que te contestó, me tomo el tiempo de volver a contestarte.
Agradezco que hayas hecho un documento y que quieras colaborar, sin embargo el documento lo veo un poco incompleto, sobre todo en el tema de estructura. Por ejemplo, en lugar de una introducción, o de unas palabras explicando de qué va el documento, el primer texto que puedes leer es el siguiente:
El lenguaje de programación que usen no importa mucho, creo. Yo uso Action Script de Macromedia Flash 5 pero no implica que sea el mejor lenguaje; lo uso por motivos que me extendería bastante al explicar, y no quiero extenderme en explicar eso, así que eso no lo explicaré.
¿Realmente crees que esta frase merece estar en el primer párrafo? "me extendería bastante al explicar, y no quiero extenderme en explicar eso, así que eso no lo explicaré". La primera página de tu documento es oro, es lo primero (y quizás, en este caso, lo único) que muchas personas van a leer. ¿De verdad esa frase que has escrito vale su peso en oro? De todas las frases, de todo lo que puedes explicar en la primera página, ¿es esto lo más importante?
Estás asumiendo de entrada que la gente ya sabe de qué va tu documento, no pones digamos un cesped para que la gente entre a tu casa con facilidad. Igual que en una casa el frente es importante, para que la gente lo vea y se anime a entrar, la primera página de tu documento invita a la gente a que siga leyendo. O en tu caso, a mí me ha invitado a no seguir.
Una buena primera página en mi opinión contendría información como:
- ¿Qué puedo aprender de este documento?
- ¿Qué necesito saber antes de leer el documento?
- ¿Para quién es útil este documento, y para quién no?
- ¿Quién es la persona que escribe el documento, y cuál es su experiencia?
No tengo mucho tiempo para ponerme a editar tu documento, pero el primer ejemplo lo he modificado un poco, y a mi gusto, sería algo como esto:
Así lo veo más bonito.
Y hablando de cosas bonitas: Justo en seguida de este primer ejemplo, has puesto un ejemplo que de sólo verlo me ha dado dolor de cabeza.
Este código es un horror de código, mezclando inglés, español y pésimo código fuente (de nuevo, en mi opinión). ¿Qué es eso de U=0, Us=0? ¿Por qué no usas nombres de variables que sean más claros? Me estás obligando a usar mi cerebro para entender tú código, en vez de usarlo para entender lo que me estás tratando de enseñar. Es como intentar leer un libro en un idioma extranjero sobre poesía. Ya te puede gustar mucho la poesía, que si no entiendes una jota de lo que pone, tu cerebro va a estar trabajando en vano.
¿Te has dado cuenta que te hicieron falta 3 páginas para explicar el código? En lugar de escribir de forma bonita, un programa que se entienda leyendo el código fuente, has incluido un código confuso, que requiere 3 veces más texto para entender lo que hace. ¿Te suena aquello del
Clean Code?
Una cosita más: Nunca digas
Intentaré explicarlo (no se me da bien):
Si ya de entrada me dices que no se te da bien, ¿por qué se te tendría que dar bien escribir un documento sobre el tema? Me estás pidiendo que lea un documento que tú mismo estás diciéndome no se te da bien explicar.
Nunca, nunca digas "no se me da bien", "no lo hago del todo bien", "no soy muy experto." Al menos, no en un tutorial. Tienes que estar seguro de lo que sabes, tienes que saber expresarlo y saber que sabes expresarlo.
No te vendas con descuento
Saludos!