StyleGuide

This page tries to help people be better writers on this wiki. It belongs to the HowToEdit group of pages.

Be short. Long pages make things hard to find.

Use headers. A table of contents will be created for every page containing several headers.

Use bold (*bold*) to make text easy to skim.

If things are important for older versions, clearly separate them from the main body of the page using headers.

Delete stuff that is no longer relevant.

Avoid discussion of stuff that’s outdated or wrong. Just rewrite it to be up to date and correct. If there is a discussion, take it to the talk pages (follow the Talk link at the bottom) or make the discussion obvious to future readers by using a header (“Discussion”) and separating contributions using [new].

Write as if you are talking to someone.

You can ask people on the EmacsChannel to peer review your contribution.

When saving a page, please make sure you add a summary. Just copy and paste a sentences from the text you wrote or mention a keyword or two. It helps others that are following along on RecentChanges.

Here are some references for more information about writing online:

The following comment was made in an edit on EmacsNewbie:

Does a newbie need any more bulletpoints than necessary? Let’s reformat this into more prose and less bullet points, to make this more coherent and less jarring. – StudentRadical?

I don’t know how prose is always better than lists. Itemized lists are pretty simple and good for navigation on the Web (and in Info!) and easier to maintain and likely translate.

The issue is more of the Wiki practice of referencing every page in a category, of which EmacsNewbie is one, rather than having a thoughtful navigation of the pages in a category. “Writing as if you are talking to someone” is important. It’s not the only requirement for the Web though. – AaronHawley


HowTo