[pyar] Writing a README

[Ricardo Daniel Quiroga]

Bueno entonces todo el mundo escribimos mal los archivos README, solo dice
que es un documento que acompaña
en el cual hay información de relevancia sobre éste en cuanto a su uso,
nuevas características, errores (bugs) y requisitos
de hardware.

Si esto esta equivocado pues bueno tomate la molestia de corregir la
definición en wikipedia.

ahh que hermoso "pip install -r requeriments.txt"

bueno te pregunto en windows, incluime el requerimiento de  un paquete como
pygraphviz  (que viene con django_extensions)
y decime si deberia siempre decir eso.

Saludos

El 7 de mayo de 2014, 16:34, Martín Gaitán <gaitan en gmail.com> escribió:

> el tópico "documentación" es algo que me interesa mucho. En el último
> PyDay de córdoba (se viene otro?!) en 2012, di una charla sobre este tema
> que se tituló "__doc__ para todos y todas". La "bajada" decía así
>
> No existe software de calidad sin una documentación que lo demuestre. Y
> Python no sólo se destaca como lenguaje y comunidad: también por su
> "cultura de la documentación". La charla dará ideas, herramientas,
> servicios y demás yerbas para ser un pythonista de ley, documentado.
>
>
>
>
> diapositivas:   http://mgaitan.github.com/charla__doc__/presentacion.html
> repo:   http://github.com/mgaitan/charla__doc__/
>
> en las propias diapos hay algunas referencias interesantes. En particular
> al proyecto "Read the docs" y sus proyectos derivados, entre las que se
> encuentra la conferencia "Write the docs" que acaba de tener una nueva
> edición (terminó ayer)
>
> http://conf.writethedocs.org/na/2014/
>
> y acá la "doc" de "write the docs"
>
> http://write-the-docs.readthedocs.org/
>
>
> salú
>
>
>
>
> 2014-05-07 16:10 GMT-03:00 Roberto Alsina <ralsina en netmanagers.com.ar>:
>
>  On 07/05/14 16:05, Ricardo Daniel Quiroga wrote:
>>
>> primero que nada pondria aunque soy medio vago para hacerlo cuando son
>> proyectos personales
>> que aunque vivan en repositorios publicos como github no estoy interesado
>> en tomarme el trabajo
>> de distribuirlos pero en fin deberia tener al menos.
>>
>> que hace y que no hace
>>
>>
>> El "que no hace" un programa es infinito! :-D
>>
>>   quienes lo hicieron
>>
>>
>> AUTHORS.txt o CONTRIBUTORS.txt
>>
>>   requerimientos
>>
>>
>> Ponele, pero muy los de alto nivel.
>>
>>
>>   instalacion
>> como se usa (aunque una wiki andaria mejor)
>>
>>
>> No, eso va en el manual. En el README poné un ejemplo.
>>
>> Un README no puede ser más de una o dos pantallas de texto, si no, estás
>> escribiendo un manual.
>>
>>
>>
>>
>>
>> El 5 de mayo de 2014, 21:25, Angel Java Lopez <ajlopez2000 en gmail.com>
>> escribió:
>>
>>> Otra cosa que agregaria:
>>>
>>>  - En que lenguaje esta escrito
>>>
>>
>> No, eso va en HACKING.txt o algo así.
>>
>>
>>    - Para que version esta preparado (p.ej. si es Python, que diga
>>> explicitamente que versiones de Python soporta)
>>>
>>
>> Depende. Si recomendás instalarlo via PyPI, es mas importante ponerlo en
>> la metadata del paquete.
>>
>>
>>    - En que plataformas corre
>>> - Como ejecutar los tests
>>>
>>
>> En HACKING.txt
>>
>>
>>    - Como instalar las dependencias
>>>
>>
>> Debería siempre decir "pip install -r requirements.txt" :-)
>>
>>
>>    - Los casos de uso a los que esta dirigido
>>> - etc... etc...
>>>
>>>  Hay varios proyectos que ASUMEN que todos sabemos esas cosas, pero
>>> snif... no es el caso ;-)
>>>
>>>  No se, tal vez no se habitua lo de arriba, pero a mi me parece que
>>> reduce friccion.
>>>
>>>  Me encontre con descripciones tipo:
>>>
>>>  "Herramienta que tira pirulines"
>>>
>>>  pero que en realidad era:
>>>
>>>  "Herramienta que tira pirulines en Django, no para Ruby o Node.js, en
>>> Django, entiendan, y solo para tirar pirulines cuando se deploya en Heroku,
>>> no pidan otra cosa, ah, y no se maten, solo corre con Python 2.7"
>>>
>>>  No se, digo ;-)
>>>
>>>  Nos leemos!
>>>
>>>  Angel "Java" Lopez
>>> @ajlopez
>>>
>>>
>>> On Mon, May 5, 2014 at 8:27 PM, Pedro Jose Pezzarini <jose2190 en gmail.com
>>> > wrote:
>>>
>>>> absolutely  great for this lines:
>>>> - Install the shit.
>>>> - Run it.
>>>> - Look for error messages.
>>>>
>>>>
>>>> 2014-05-05 20:10 GMT-03:00 Apokalyptica Painkiller <
>>>> apokalyptica79 en gmail.com>:
>>>>
>>>>>  Good documentation is important. I just heard two colleagues talking
>>>>> and what one of them said sounded like a README.
>>>>>
>>>>>  Writing a readme
>>>>> <http://reinout.vanrees.org/weblog/2014/05/05/writing-a-readme.html>
>>>>>
>>>>>  --
>>>>> I live each day
>>>>> Like it's my last
>>>>> I live for rock and roll
>>>>> I never look back
>>>>>
>>>>> I'm a rocker
>>>>> Do as I feel as I say
>>>>> I'm a rocker
>>>>> And no one can take that away
>>>>>
>>>>>
>>>>>  _______________________________________________
>>>>> pyar mailing list pyar en python.org.ar
>>>>> http://listas.python.org.ar/listinfo/pyar
>>>>>
>>>>> PyAr - Python Argentina - Sitio web: http://www.python.org.ar/
>>>>>
>>>>> La lista de PyAr esta Hosteada en USLA - Usuarios de Software Libre de
>>>>> Argentina - http://www.usla.org.ar
>>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> pyar mailing list pyar en python.org.ar
>>>> http://listas.python.org.ar/listinfo/pyar
>>>>
>>>> PyAr - Python Argentina - Sitio web: http://www.python.org.ar/
>>>>
>>>> La lista de PyAr esta Hosteada en USLA - Usuarios de Software Libre de
>>>> Argentina - http://www.usla.org.ar
>>>>
>>>
>>>
>>> _______________________________________________
>>> pyar mailing list pyar en python.org.ar
>>> http://listas.python.org.ar/listinfo/pyar
>>>
>>> PyAr - Python Argentina - Sitio web: http://www.python.org.ar/
>>>
>>> La lista de PyAr esta Hosteada en USLA - Usuarios de Software Libre de
>>> Argentina - http://www.usla.org.ar
>>>
>>
>>
>>
>>  --
>> ------------------------------------------------------------
>> Ricardo Daniel Quiroga - L2Radamanthys
>>
>>    Msn: l2radamanthys en gmail.com
>>            ricardo_quiu en hotmail.com
>>
>>    Email: l2radamanthys en gmail.com
>>            l2radamanthys en saltalug.org.ar
>>            ricardoquiroga.dev en gmail.com
>>
>>    sitio Web: http://www.l2radamanthys.com.ar
>>                    http://github.com/L2Radamanthys
>>
>>    Facebook: http://es-la.facebook.com/L2Radamanthys
>>    Twitter:    @l2Radamanthys
>> ---------------------------------------------------------
>>
>>
>> _______________________________________________
>> pyar mailing list pyar en python.org.arhttp://listas.python.org.ar/listinfo/pyar
>>
>> PyAr - Python Argentina - Sitio web: http://www.python.org.ar/
>>
>> La lista de PyAr esta Hosteada en USLA - Usuarios de Software Libre de Argentina - http://www.usla.org.ar
>>
>>
>>
>> _______________________________________________
>> pyar mailing list pyar en python.org.ar
>> http://listas.python.org.ar/listinfo/pyar
>>
>> PyAr - Python Argentina - Sitio web: http://www.python.org.ar/
>>
>> La lista de PyAr esta Hosteada en USLA - Usuarios de Software Libre de
>> Argentina - http://www.usla.org.ar
>>
>
>
>
> --
> mgaitan.github.io
> textosypretextos.com.ar <http://textosyprextextos.com.ar>
>
> _______________________________________________
> pyar mailing list pyar en python.org.ar
> http://listas.python.org.ar/listinfo/pyar
>
> PyAr - Python Argentina - Sitio web: http://www.python.org.ar/
>
> La lista de PyAr esta Hosteada en USLA - Usuarios de Software Libre de
> Argentina - http://www.usla.org.ar
>



-- 
------------------------------------------------------------
Ricardo Daniel Quiroga - L2Radamanthys

   Msn: l2radamanthys en gmail.com
           ricardo_quiu en hotmail.com

   Email: l2radamanthys en gmail.com
           l2radamanthys en saltalug.org.ar
           ricardoquiroga.dev en gmail.com

   sitio Web: http://www.l2radamanthys.com.ar
                   http://github.com/L2Radamanthys

   Facebook: http://es-la.facebook.com/L2Radamanthys
   Twitter:    @l2Radamanthys
---------------------------------------------------------
------------ próxima parte ------------
Se ha borrado un adjunto en formato HTML...
URL: <http://listas.python.org.ar/pipermail/pyar/attachments/20140916/a6a2f136/attachment-0001.html>