[pyar] Writing a README

[Martín Gaitán]

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>
------------ próxima parte ------------
Se ha borrado un adjunto en formato HTML...
URL: <http://listas.python.org.ar/pipermail/pyar/attachments/20140507/3a9cd6b1/attachment-0001.html>