CZ:Computers Workgroup: Difference between revisions
imported>Howard C. Berkowitz (Added RFC2119 conventions for protocol, etc., behavior description) |
imported>Howard C. Berkowitz (Writing and style guides) |
||
| Line 23: | Line 23: | ||
==What's happening right now in the Computers Workgroup?== | ==What's happening right now in the Computers Workgroup?== | ||
To find out, view this workgroup's [http://en.citizendium.org/wiki?title=Special:Recentchangeslinked&target=Category:Computers_Workgroup Recent Changes]. | To find out, view this workgroup's [http://en.citizendium.org/wiki?title=Special:Recentchangeslinked&target=Category:Computers_Workgroup Recent Changes]. | ||
==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.[[User:Howard C. Berkowitz|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. [[User:Howard C. Berkowitz|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 <nowiki>{{subpages}}</nowiki> 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.[[User:Howard C. Berkowitz|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== | ==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.[[User:Howard C. Berkowitz|Howard C. Berkowitz]] 15:20, 23 October 2008 (UTC) | |||
===Denoting requirements and optional behavior=== | |||
When describing optional, mandatory, or forbidden behavior of a [[protocol (computer)|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".<ref name=RFC2119>{{citation | When describing optional, mandatory, or forbidden behavior of a [[protocol (computer)|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".<ref name=RFC2119>{{citation | ||
| title = Key words for use in RFCs to Indicate Requirement Levels | | title = Key words for use in RFCs to Indicate Requirement Levels | ||
| Line 53: | Line 68: | ||
|- | |- | ||
|} | |} | ||
[[User:Howard C. Berkowitz|Howard C. Berkowitz]] 15:20, 23 October 2008 (UTC) (I did this a while ago but forgot to sign it) | |||
==References== | ==References== | ||
{{reflist}} | {{reflist}} | ||
Revision as of 09:20, 23 October 2008
Workgroups are no longer used for group communications, but they still are used to group articles into fields of interest. Each article is assigned to 1-3 Workgroups via the article's Metadata. |
|
| ||||||||
| Computers article | All articles (1,099) | To Approve (0) | Editors: active (3) / inactive (77) and Authors: active (815) / inactive (0) |
Workgroup Discussion | ||||
| Recent changes | Citable Articles (12) | |||||||
| Subgroups (11) | ||||||||
Checklist-generated categories:
Subpage categories:
|
Missing subpage categories:
Article statuses:
| ||||||||
The Computers Workgroup coordinates the Citizendium articles related to computers and computer science.
Help plan Computers Week!
Authoring
Anyone is welcome to participate in improving, or adding to, the Computers_Workgroup articles. To author for this workgroup, please add [[:Category:Computers Authors]] to the bottom of your user page so it appears on the Category:Computers Authors page. Likewise, Editors should have [[:Category:Computers Editors]] at the bottom of their user page so they'll appear on the Category:Computers Editors page.
Communication
Although we have a forum, it is being phased out in favor of the workgroup email list (please subscribe to this list; it is used sparingly but is the only way to reach everyone all at once). The Talk page for this article is also a place where policy issues can be discussed.
Adding or removing articles
To add an existing or new article to the this workgroup, edit the article and add [[Category:Computers Workgroup]] to the bottom of the page. The article should then appear in one of the article clusters shown in the table above, depending on whether or how it is checklisted on its Talk page.
Urgently needed articles
Some authors have made an attempt to catalog the basic articles which we still need to start. You can find a list of the needed core articles at Core articles.
Recruiting people
We are actively seeking more authors and editors for this workgroup. Here is a potential recruitment letter; please consider inviting to your colleagues to join us.
What's happening right now in the Computers Workgroup?
To find out, view this workgroup's Recent Changes.
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)
References
- ↑ S. Bradner (March 1997), Key words for use in RFCs to Indicate Requirement Levels