Scheduled Maintenance: We are aware of an issue with Google, AOL, and Yahoo services as email providers which are blocking new registrations. We are trying to fix the issue and we have several internal and external support tickets in process to resolve the issue. Please see: viewtopic.php?t=158230

 

 

 

[Read-Me] How to post a thread here

Share your HowTo, Documentation, Tips and Tricks. Not for support questions!.
Locked
Message
Author
User avatar
Hallvor
Global Moderator
Global Moderator
Posts: 2020
Joined: 2009-04-16 18:35
Location: Kristiansand, Norway
Has thanked: 138 times
Been thanked: 204 times

[Read-Me] How to post a thread here

#1 Post by Hallvor »

This text provides tips and expectations for those who are thinking of posting a how-to.

1. Before writing
Know your readers, know your stuff and know that it works.

Know your readers

Who are you writing for? Beginners? Intermediate users? Advanced users?

Know your stuff

Please don’t copy-paste stuff from the Internet without having enough knowledge of the topic at hand. The blind can’t lead the blind.

Know that it works

We expect you to have tested the actual commands on your own hardware to verify that it works.


2. Structure your how-to


Do a brainstorm

Grab a piece of paper and write down everything you want to include in your how-to.

Make an outline

Then sort your topics and create sensible headlines if necessary.


3. Write the how-to

Once your outline is ready, you can start writing.

Always include this
* The Debian version you have tested in on
* If you need packages from contrib or non-free
* How to undo system wide changes, for instance when editing low level configuration files
* Credits/sources, if you have used them. (Only use the best you can find)

Keep it simple

Show your skills by making it as easy to follow as possible, thereby increasing it’s relevance. It’s easy to write about a complex topic in a complex manner, but it takes great understanding and skill to to make it look easy.

Use the correct level of detail

Adapt the level of detail to your target audience. Beginners may need precise instructions on how to elevate privileges, open, edit and save a configuration file in nano. Intermediate and advanced users may only need to be told to edit a certain file. If in doubt, see the point above.

Use active headings
Look at the headings above. They are all orders, telling what to do. This makes the how-to clear and easy to follow.

Use topic sentences and commentary sentences in paragraphs
The first sentence in a paragraph should always give you a summary or an idea of what the entire paragraph is about. This makes the text easier to read. (Notice how the first sentence is a topic sentence, and that the following is a commentary sentence giving details to the first.)

Don’t write more than necessary to get your message across

Long posts with large blocks of text are hard to read, so avoid it if necessary.

Use code brackets
Again, this makes the how-to easier to read.

Explain what your commands do

New users (and advanced users alike!) will be uneasy about executing unknown commands. Please give a very short description of what the command does, and explain any used parameters.

Proof read

Check your spelling and grammar, and make sure that the commands you post are correct. Many people will likely read and test your how-to, and a how-to that doesn’t work as stated is wasted time for all. That includes yours.


4. After publishing

* Relax and know that others will appreciate your hard work

* It is encouraged to respond in a timely manner if you get questions

* Edit and improve your post if necessary. If you have altered or added code, please make a log entry at the bottom of the post with date and changes, for instance:

«13.10.22: Edited typo in configuration file», or
«14.10.22: Added rm-command»

Don’t worry about mistakes – they are what make us human.
[HowTo] Install and configure Debian bookworm
Debian 12 | KDE Plasma | ThinkPad T440s | 4 × Intel® Core™ i7-4600U CPU @ 2.10GHz | 12 GiB RAM | Mesa Intel® HD Graphics 4400 | 1 TB SSD

Locked