Editing guidelines

From Linux Raid Wiki
(Difference between revisions)
Jump to: navigation, search
(Create initial page)
 
("bitty" => "incoherent"; "Plus," => "Besides,"; plus minor elaboration.)
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
The guidelines are simply to ensure a consistent feel to the site. It's not nice to read a site that's horribly bitty, and it's not fair on the editors to expect them to fix everything. Plus, certain things will make it easier for newbies to get to grips with good practice :-)
+
The guidelines are simply to ensure a consistent feel to the site. It's not nice to read a site that's horribly incoherent, and it's not fair on the editors to expect them to fix everything. Besides, highlighting a few rules of thumb will make it easier for newbies to get to grips with good practice :-)
  
 
When referring to arrays, always refer to generic arrays as /dev/mdN (N for a random number) or as /dev/md/name if referring to a specific array. Users should be encouraged in real life always to create and refer to arrays by name, as the number tends to change a bit at random.
 
When referring to arrays, always refer to generic arrays as /dev/mdN (N for a random number) or as /dev/md/name if referring to a specific array. Users should be encouraged in real life always to create and refer to arrays by name, as the number tends to change a bit at random.
Line 8: Line 8:
  
 
While it's important to adopt a professional writing style, I'm a scientist. And I *HATE* the use of the 3rd person. It lends a false aura of authority and infallibility. The best scientists wrote in the 1st person. 1st person text is nice to read. And 1st person text takes *personal* responsibility.
 
While it's important to adopt a professional writing style, I'm a scientist. And I *HATE* the use of the 3rd person. It lends a false aura of authority and infallibility. The best scientists wrote in the 1st person. 1st person text is nice to read. And 1st person text takes *personal* responsibility.
 +
 +
Some topics are just controversial. It's fine to let your prejudices show, provided that's obvious to the reader. Just be honest about the pros of the other approaches, and the cons of your preferred choice. Remember that one size does NOT fit all.
  
 
And just read the site. Get a feel for how it's written. Try and keep your writing in the same style as everything else.
 
And just read the site. Get a feel for how it's written. Try and keep your writing in the same style as everything else.
  
 
NB. I'm English. I speak and write English, not that old-fashioned American :-) But I won't insist you use our weird spellings. Just use a consistent dialect of a native English speaker (any English dialect).
 
NB. I'm English. I speak and write English, not that old-fashioned American :-) But I won't insist you use our weird spellings. Just use a consistent dialect of a native English speaker (any English dialect).

Latest revision as of 23:08, 21 March 2017

The guidelines are simply to ensure a consistent feel to the site. It's not nice to read a site that's horribly incoherent, and it's not fair on the editors to expect them to fix everything. Besides, highlighting a few rules of thumb will make it easier for newbies to get to grips with good practice :-)

When referring to arrays, always refer to generic arrays as /dev/mdN (N for a random number) or as /dev/md/name if referring to a specific array. Users should be encouraged in real life always to create and refer to arrays by name, as the number tends to change a bit at random.

When referring to disks, always refer to a generic disk as /dev/sdX (or Y or Z), and when referring to specific disks, use /dev/sda (and b, and c, etc as appropriate).

Try to use UUIDs as much as possible, where appropriate. Again, it's just good practice to use them as much as possible in real life, so use them in the documentation and the examples.

While it's important to adopt a professional writing style, I'm a scientist. And I *HATE* the use of the 3rd person. It lends a false aura of authority and infallibility. The best scientists wrote in the 1st person. 1st person text is nice to read. And 1st person text takes *personal* responsibility.

Some topics are just controversial. It's fine to let your prejudices show, provided that's obvious to the reader. Just be honest about the pros of the other approaches, and the cons of your preferred choice. Remember that one size does NOT fit all.

And just read the site. Get a feel for how it's written. Try and keep your writing in the same style as everything else.

NB. I'm English. I speak and write English, not that old-fashioned American :-) But I won't insist you use our weird spellings. Just use a consistent dialect of a native English speaker (any English dialect).

Personal tools