Reglas de documentación

De gulBAC wiki

Introducción

La idea de GRg no es solo publicar buenas soluciones, sino publicarlas bien. Pretendemos que la documentación sea concisa, efectiva, útil y prolija. Por eso es importante documentar poniendo atención a los detalles. Por esa razón hemos escrito esta pequeña guía para documentar en GRg, las llamadas Reglas de documentación que deberás tener en cuenta al momento de publicar.

Eligiendo un titulo para tu guía

Es muy importante empezar con el pie derecho; elegí un nombre claro que describa claramente el contenido de la guía. Buscá usar las palabras más importantes y descriptivas sobre el tema que trata tu artículo. Evita los nombres como: ¡Un script genial! ó Cómo podes hacer para para leer el disco de windows en linux. Para este último ejemplo sería preferible algo como Montar particiones NTFS en GNU+Linux.

Si no se te ocurre un nombre o no sabes como simplificarlo, pensá que escribirias en un buscador para encontrar la información que brinda tu guía. Por ejemplo, para el ejemplo anterior seria esperable hacer una búsqueda con un criterio similar a este: montar + ntfs + linux.

Recordá siempre que el nombre de tu guía definirá en gran parte la cantidad de visitas que tendrá o en otros término, a cuanta gente le resultara fácil encontrarla. Los primeros resultados que arroja un búsqueda en Google, por ejemplo, son casi siempre los enlaces con los nombres más descriptivos y claro, con más enlaces.

Dandole formato al artículo

Darle formato a tu texto es muy sencillo: escribir con la sintaxis de Mediawiki (Wikipedia si así lo entienden mejor).

Resulta una sintaxis excelente, simple y ordenada. Además permite hacer cosas que con la otra opción no se puede o simplemente es demasiado complicado: listas numeradas complejas, cabeceras, indices, etc. Además al ser una sintaxis de wiki permite que importemos código desde cualquier Mediawiki (el motor de Wikipedia) y claro, subir nuestro artículo a un wiki. Sepuede ademas combinar perfectamente con código en HTML (ya que de hecho la sintaxis del wiki genera HTML). Cómo esta es la opción recomendada, preparé esta guía para que aprendas la sintaxis de Mediawiki.

Insertando código fuente

Lamentablemente esta función no se puede usar en el wiki por ahora.

Para insertar código simplemente cada línea debe empezar con un espacio, y no hay resaltado de ninguna clase de sintaxis.

Además podes incluir fragmentos de código fuente y que se muestre con la sintaxis resaltada. Casi cualquier lenguaje esta soportado gracias al plugin Coding. Para usarlo simplemente debes insertar:

<pre lang="LENGUAJE">

CÓDIGO FUENTE

</pre>

• Reemplaza LENGUAJE por el que quieras. Alguno de los soportados son:
  • actionscript
  • ada
  • apache
  • applescript
  • asm
  • asp
  • autoit
  • bash
  • blitzbasic
  • caddcl
  • cadlisp
  • cfm
  • c_mac
  • c
  • cpp
  • csharp
  • css
  • delphi
  • diff
  • div
  • dos
  • d
  • eiffel
  • freebasic
  • gml
  • html
  • 4strict
  • ini
  • inno
  • java5
  • java
  • javascript
  • lisp
  • lua
  • matlab
  • mpasm
  • mysql
  • nsis
  • objc
  • oracle
  • pascal
  • perl
  • php
  • python
  • qbasic
  • robots
  • ruby
  • scheme
  • sdlbasic
  • smarty
  • sql
  • tsql
  • vbnet
  • vb
  • vhdl
  • visualfoxpro
  • xml

Categorizando tu guía

Antes de publicar tu guía recuerda definir las categorías a las que pertenece. En caso de que ninguna de las existentes se adapte a tus necesidades o no existe la que buscas, creala.

Es importante que categorices para mantener ordenado el sitio.

Para esto, agregá al final del texto lo siguiente:

[[Categoría:NOMBRE]]

Siendo 'NOMBRE' el nombre de la categoría :-P

Consejos finales

1. Revisá la ortografía: Escribi sin errores, revisá a menudo, usá mayúsculas y poné tildes. No es agradable leer documentación mal escrita y con errores infantiles. Evita el uso de abrevaciones como q o kizas. Queremos documentación que se entienda y que pueda ser adapatada por otros, por eso usemos correctamente lo que tenemos en común: EL IDIOMA.
2. Escribi bien los nombres: Por respeto a otras personas ó por simple buen gusto, escribí bien los nombres de programas, paquetes, sistemas operativos, empresas y demás. Así como no nos gusta ver escrito gulBAC de otra forma como Gulbac o cosas así, intentá escribir bien y respetar los acrónimos. Algunos ejemplos:

• Si te gusta el software libre y querés darle crédito a quienes lo hacemos posible, por favor menciona correctamente el nombre de tu sistema operativo libre. Evita escribir Linux, hacelo correctamente: GNU+Linux.
• Evita usar nombres infantiles para referirte a Microsoft Windows: no uses window$, micro$oft o guindows. Es preferible MS-Windows, si queres acortar.
• Si te referis a un paquete, no está mal que lo escribas en minúscula.

1. Recordá resaltar partes que creas importanes del texto.
2. Si te basaste en algun otro documento u otro artículo te evacuó una duda, hacé referencia a él. Es bueno dar los créditos correspondientes a quienes al igual que vos comparten su conocimiento.
3. Si tu guía lo ameríta, hacé una lista de enlaces útiles y referencias. Recorda que es una buena idea hacer referencia a alguna otra guía de GRg que esté relacionada con la tuya.
4. En el final de la guía poné tu nombre si querés y una forma de contactarte.
5. Si no querés que tu artículo este gobernado por la misma licencia que GRg (Creative Commons BY-SA 2.5 Ar / GNU FDL 2 o sup.) especificá correctamente la licencia. Poné por supuesto un enlace al texto legal correspondiente a la licencia elegida. Si no queres usar una licencia en particular, explica claramente que usos y prácticas permitis.

Acerca de las Reglas de documentación

Referencias

• Sitio de Milon Biswas, autor del plugin Coding para Wordpress

Licencia de este documento

• Dedicación al Dominio Público - Public Domain Dedication - Solo válido en el contexto legal de EEUU

Este artículo “Reglas de documentación” esta Dedicado al Dominio Público, por lo que se permite copiar, distribuir, exhibir, ejecutar libremente este artículo, hacer obras derivadas sobre el, explotarlo con cualquier finalidad, ya sea con o sin fines comerciales, incluyendo tanto los métodos conocidos como los que se desarrollen a futuro.

Autor

Franco Iacomella