Digamos que quiere hablar sobre una pieza de software de línea de comandos, como makeo basho el cpcomando. Estos comandos están todos en minúsculas y distinguen entre mayúsculas y minúsculas (es decir, no funcionarán en la computadora si los escribe en mayúsculas), y también a menudo se duplican como los nombres de los proyectos de software que escriben los programas que invocan los comandos. ¿Qué sucede cuando quieres comenzar una oración con el nombre de una de estas herramientas? ¿Cuál de los siguientes es mejor?
cates una utilidad de Unix para concatenar archivos. (Comienza la oración con una de estas extrañas cosas de cuadro de código. Requiere que esa opción de formato esté disponible, y aún terminas con una letra minúscula).¿Alguna guía de estilo aborda este problema?
La regla #1 en la documentación técnica es: no engañe al lector. Si el nombre del comando o la función comienza con una letra minúscula, escribirlo en mayúscula es un error; no es "Gato" sino "gato". El Manual de estilo de Microsoft especifica que los elementos literales como este deben escribirse con su caso correcto. También requiere el uso de estilos de texto para compensarlos, al igual que otras guías de estilo que he usado. (Microsoft favorece la negrita; otros favorecen el monoespaciado).
Sorprendentemente, en mi experiencia, las guías de estilo orientadas al software no abordan el caso específico de comenzar una oración con estos elementos. Si puede escribir sobre el problema sin hacer que la documentación sea más engorrosa , he descubierto que es mejor hacerlo. En vez de
cates una utilidad de Unix para concatenar archivos.
Es posible que puedas escribir
Úselo
catpara concatenar archivos.
podrías escribir
La
catutilidad concatena archivos.
Sin embargo, esto puede volverse engorroso o inconsistente rápidamente: si dice "la catutilidad" en algunos lugares pero " cat" en otros lugares, deja a los lectores preguntándose por qué. Pero si usa la formación anterior en todas partes, hace que la documentación sea más difícil de escanear y agrega palabras adicionales aparentemente innecesarias.
Los equipos de documentación de software de los que he formado parte durante los últimos 20 años han seguido esta directriz: escribe alrededor del problema si puedes hacerlo razonablemente y, si no puedes, simplemente comienza la oración con el nombre en minúsculas. . El uso de estilos de texto para los nombres de comando/función/etc mitiga el "error" de mayúsculas.
El sitio de GNU trata el nombre de la utilidad Make como una palabra en mayúsculas: https://www.gnu.org/software/make/
Parece haber una convención para usar con frecuencia make(el comando) donde Make (el nombre) parecería más apropiado. El manual GNU Make parece hacer esto casi exclusivamente ( https://www.gnu.org/software/make/manual/make.html ) pero siempre con un cambio de fuente para indicar que es el comando que se está utilizando.
Entonces esos ejemplos justificarían la segunda y tercera opción para Make, aunque el manual parece evitar el uso makeal comienzo de una oración.
Sin embargo, está menos claro que cpo catpueda tratarse de esta manera. Son comandos más que productos independientes como Make. Me inclinaría a evitar usarlos como nombres independientes y, en su lugar, usaría "El catcomando" como en:
El
catcomando se utiliza para concatenar archivos.
catconcatena archivos. 2. Use catpara concatenar archivos.
Raddevus