CZ Talk:Computers Workgroup/Writing Guide
This is linked from CZ_Talk:Computers_Workgroup
A writing guide before a style guide
Style guides, as I see them, set up rules, or at least very strong recommendations. For computers, that's in the next section; I may wikilink to some things for other workgroups. I want to thank Chris Day and Sandy Harris for some discussions that led to the ideas here.Howard C. Berkowitz 15:20, 23 October 2008 (UTC)
Scope of articles
Some people are top-down and others are bottom-up writers. There's plenty of room for both, but I'm increasingly of the opinion that major topics need some organizing pages.
(temporary note) I really could use help on communications security, which doesn't have metadata because I'm not happy with the title, which should encompass things that live completely on a computer, as well as only in radio links. Some people call this information assurance, but I've just never liked that term. Howard C. Berkowitz 15:20, 23 October 2008 (UTC)
When and how to create and split articles
There's no pure rule. Eventually, a section of an article will start demanding its own article. In other cases, you may recognize that a subtopic will eventually need its own article. More and more, I'm tending to create stubby articles, subject to some constraints.
I am leaning more and more not just to leaving a pink (magenta? red?) link, but at least going and creating the page, if only I copy the introduction from the main article. I don't necessarily fill out all the metadata, but I am finding shortcuts -- I often copy, and then just slightly edit, the definition in the introduction (I hate "lede") of the main article, or begining of a subsection. I don't believe definitions are useful for most articles themselves, but Chris Day is getting me more and more convinced of the need for definitions for use in R-templates on Related Articles and Disambiguation pages. For me, at least, the thing I hate about putting in {{subpages}} is that definition staring at me.
When creating the talk page, I've found it useful, if just for myself, to put, even before a first heading, the motivation for writing the article, things that it needs, and things to which it relates. The optional "Related Article" page also is a good way to capture aspects of a plan.Howard C. Berkowitz 15:20, 23 October 2008 (UTC)
Naming articles
When creating stubs, think long and hard about the title. There is a proposal to allow separation between the internal page name and the title, which will help a lot. Otherwise, for an assortment of reasons, disambiguation from other fields' usage of the term being the most important, think long and hard before using an abbreviation as a title. IPsec is a legitimate exception, although there probably need to be IPSec and IPSEC redirects, as well as Internet Protocol Security (and maybe IP Security Architecture).
Starting on a style guide
Easy way to get monospace (as for copying ASCII art
Leave one space on the left. As long as the line has a hard carriage return (e.g., the message layouts in IETF documents), you'll be fine.Howard C. Berkowitz 15:20, 23 October 2008 (UTC)
Denoting requirements and optional behavior
When describing optional, mandatory, or forbidden behavior of a protocol or comparable mechanism, key words to describe this behavior, to be written in ALL CAPs, are to be interpreted as described in RFC 2119, "Key words for use in RFCs to Indicate Requirement Levels".[1]
| Keyword | Meaning |
|---|---|
| MUST, SHALL, REQUIRED | Absolute requirements |
| MUST NOT, SHALL NOT | Absolute prohibition |
| SHOULD, RECOMMENDED | there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course |
| SHOULD NOT, NOT RECOMMENDED | there may exist valid reasons in particular circumstances when theparticular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label |
| MAY, OPTIONAL | Makes the feature truly optional and an implementation choice. Implementations that do not have the feature, howeever, MUST be able to interoperate with those that do not, and vice versa |
Howard C. Berkowitz 15:20, 23 October 2008 (UTC) (I did this a while ago but forgot to sign it)
- ↑ S. Bradner (March 1997), Key words for use in RFCs to Indicate Requirement Levels