Правила и съвети за писане на ръководства

[Night_Raven]

Преди да се оплачете от нещо, моля прочетете настоящата тема. В нея се описват някои задължителни правила, които трябва да се спазват при писане на ръководство, както и съвети и препоръки. Прочетете я внимателно! Ако имате предложения или въпроси, предлагайте/предлагайте без да се притеснявате. Темата е точно за това.

 

Наблюдава се засилващ се интерес към този раздел не само откъм четящите, но и откъм авторите. Все повече хора се решават да напишат ръководство за дадена програма, което може само да ни радва. И все пак форумът е сериозно място и е редно всичко, което се публикува, да е издържано като съдържание и да има добър вид.

За целта е направен специален раздел ("Ръководства в процес на разработка"), чиято цел е всеки, който желае да напише материал, да има къде да го публикува и обработва преди да го пусне в официалния раздел. Това е един вид чернова. Разделът се вижда само от регистрирани потребители.

Ще се опитам да очертая някои правила при създаване на ръководство и да дам съвети и напътствия.

 

Съдържанието на темата подлежи на промяна.

 

Какви видове ръководства има всъщност?

Ръководствата могат да се разделят на теоретически и практически:

- Теоретическите са тези, които описват подробно дадена програма (менюта, настройки и функции) и дават съвети за добра настройка на програмата и как ефективно да се ползва. Прилагат се снимки (скрийншоти) за по-добро визуално възприемане на информацията. Ако програмата е наистина доста обемна, може да се наблегне на по-важните опции, но ако програмата е малка, то е редно да се опише цялата. Не е редно да се пише ръководство за малка програма и да се опишат няколко опции ей така набързо и това да се счита за ръководство.

- Практическите ръководства се концентрират върху изпълняването на конкретни задачи. Обяснява се подробно изпълнението на действието и се дават съвети и разяснения. Прилагат се и снимки (скрийншоти) за по-лесно запомняне на извършваните действия.

 

На какви програми да се правят ръководства?

Ясно е, че програми като Notepad и калкулатора на Windows например нямат нужда от ръководства. Пишете ръководства за програми, които познавате добре и сте убедени в това, което пишете. Ако просто си търсите дадена програма, за да се разпишете, по-добре не го правете. Писане на ръководство за не много ясна за вас програма е нежелателно. По този начин можете да объркате и заблудите потребителите и кой знае това до какви последствия може да доведе. Освен това ще се чувствате неловко ако ви се зададе въпрос относно програмата и вие не можете да отговорите. Вместо да напишете недобро ръководтсво, по-добре използвайте времето и правете това, което го можете добре. Така ще помогнете повече на форума, а и на себе си.

Да повторя: ако наистина имате желание да направите ръководство, нека да е на програма, от чието ръководство наистина би имало смисъл и нека ръководствата са максимално подробни и изчерпателни.

Ако дадено ръководство бъде сметнато за непълно, ненужно или зле написано, ще бъде осъществена връзка с автора му за уточняване на ситуацията.

 

Съдържание и стил

Независимо дали пишете практическо ръководство за дадена програма (как да се извършат конкретни действия с нея) или пишете по-скоро описание на програмата и разяснявате опциите й, всичко е редно да бъде обяснено на достъпен и лесен за асимилиране език. Не бива да е на твърде висок стил, защото по-неопитните потребители ще изпитват затруднения при четенето, но не бива и да е прекалено елементарно, защото може да е изнервящо, а и не се научават нови неща. При напипването на златната среда се получава материал, в който все пак има терминология, но е поднесена така, че потребителят хем разбира материала, хем научава нещо ново и обогатява знанията си, а именно това е целта ни.

Ето и още:

- В началото на материала включете информация за програмата: официална страница, линк за изтегляне, лиценз, размер и някоя друга характерна особеност ако сметнете за необходимо.

- Напишете нещо за увод. Опишете с няколко изречения за какво е програмата, какво ще се опише в ръководството и всяка друга информация, която да спомогне четящият потребител да премине плавно към същината.

- Драснете и нещо и за заключение. Цяло ръководство сте написали, за някой-друг ред заключение ли ще се скръндзите. Придава на материала завършен и стегнат вид.

- Въздържайте се от използването на транскриптирани чужди думи като "сейвам", "лоуднете", "едитвам" и др. По-опитните потребители ще е ориентират, но за по-начинаещите, такива думи действат объркващо. Освен това и звучат глупаво. Използвайте българските преводи като "запазвам", "заредете", "редактирам".

- Не бъдете лаконични, обяснявайте по-подробно, особено неща, които сметнете за тънкост.

- Можете да ползвате помощни средства, но избягвайте да предоставяте само един превод на помощния файл, освен ако той не е наистина изчерпателен и добре обяснен. Просто включената в помощния файл информация не винаги е достатъчна и ръководството ще е непълно. И все пак...

- ...ако смятате, че помощния файл е достатъчно изчерпателен и решите да го преведете (или превеждате готова информация отнякъде), укажете това в ръководството и споделете източника. Редно е да се знае откъде е взет текста, който сте превеждали/ползвали, а и няма нищо срамно да се преведе вече готов текст. Това също си е труд.

- Нека материалите са писани на "вие". Не "Вие", не "ти", а "Вие". Дори и да пишете нещо по заявка на някой потребител, вие го пишете за всички и е редно да се обръщате подобаващо. Изписването на "Вие" с главна буква означава обръщане към един човек, затова, когато се налага да изписвате местоимението, пишете го с малка буква.

- Всеки материал е желателно да бъде съпровождан от картинки от програмата (скрийншоти). Те служат за илюстрация на думите ви и са съществена част от всяко ръководство, не ги пренебрегвайте.

- Избягвайте използването на емотикони. Не пречи да има някоя-друга, но все пак пишете ръководство, а не фейлетон.

 

Оформяне на текста и изглед

Информацията и съдържанието са едната страна на монетата, а как ще изглежда всичко това - другата. Желателно е всичко да има чист и спретнат вид. Използвайте удебелен шрифт, курсив, подчертаваща линия и цветове, но не прекалявайте. Това са много полезни екстри и спомагат материала да изглежда добре и да улеснява четящия потребител. Мислете за тях като подправки към ястие - без тях е постно, но и никой не обича пресолено ястие, нали така.

И още:

- Старайте се да пишете правилно и грамотно. Всеки материал ще бъде преглеждан за правописни, пунктуационни и други подобни "козметични" грешки, които ще бъдат коригирани, но това все пак не пречи да се стараете при писането.

- За основен текст на материала използвайте стандартния размер и цвят. Не пишете материала си изцяло в удебелен шрифт или в някакъв цвят. Същото важи и за размера на буквите - използвайте го само, когато е нужно.

- Когато ползвате картинки и са доста големи, е желателно да ги оразмерявате за да не излизат извън пределите на екрана и да развалят структурата на текста.

- Когато давате дълги линкове, по-прегледно е да са в следния вид: тема, а не http://www.softvisia.com/forums/index.php?showtopic=1654 (линкът води към текущата тема).

- Не пишете "незнам", а "не знам". "Не" е отделна дума.

- Избягвайте съкращения. Не заменяйте един/една/едно с "1". Избягвайте да използвате "в/у" за "върху" , "м/у" за "между" и др. Съкращения като "т.н.", "др." не се броят.

 

Други

- Запазвайте картинките в PNG или GIF формат. Това са формати без загуба на качество и за скрийншоти на програми са по-добри от JPG както откъм качество, така и откъм размер. Особено PNG.

- Ако имате нужда да качвате картинки някъде, това може да стане както на отделни хостове, така и на SoftVisia. По ваше желание ще ви бъде заделено пространство на FTP сървъра на SoftVisia с първоначален размер на 10MB, където ще можете да си качвате картинки и други файлове, които са ви нужни за ръководството/статията. Просто се свържете с администратор по лично съобщение и мястото ще ви бъде отпуснато. При нужда отпуснатото пространство ще бъде увеличено. За целта отново се свържете с администратор или модератор. Ако по някаква причина не желаете да ползвате SoftVisia като хост на картинките си можете да ги качвате на http://imageshack.us/, http://www.picvalley.net/ или http://www.photobucket.com/. Последният сайт изисква безплатна регистрация.

- Укажете в края на материала си, че той е ваш и че е забранено възпроизвеждането му, както и на части от него без разрешението ви. Нека има.

- Ако ви потрябва речник, ето безплатен, онлайн такъв на сайта на Eurodict.

 

Съдържанието на темата подлежи на промяна. Приемат се идеи какво още да се добави към темата.

[Night_Raven]

Пояснение за изображенията:

Защо PNG (или GIF) вместо JPG? PNG и GIF са lossless формати (без загуба на качество), докато JPG е lossy (със загуба на качество). PNG е проектиран като подобрен наследник на GIF и в много отношения е така. Той използва метод на отгатване какъв ще е цвета на следващия пиксел на реда в картинката на базата на предишния и изважда предполагания цвят от истинския такъв. Така компресията е по-ефективна отколкото ако се направи стандартна компресия на целия ред. Особено ако следващия ред е подобен на предишния, а в шотове на прозорци в Windows (и подобни) изображенията са еднотипни, с малко на брой цветове и с резки промени в цветовете. Тук се проявява силата на PNG. JPG е проектиран за компресия на по-сложни картинки като тапети (wallpapers), и други по-големи и с плавно преливащи се цветове изображения. Той се проваля тотално при компресирането на прости картинки. Преди да премина към картинките за доказателство и сравнение ще обърна внимание, че PNG има по-добра компресия от GIF, но понякога не изглежда така. Зависи какъв софтуер ще се използва за конвертиране на изображението. Понеже GIF форматът е ограничен до 256 цвята, а PNG не е, някои софтуерни продукти не намалят цветовата палтира при компресиране в PNG и потребителят може да остане с впечатление, че PNG има по-лоша степен на компресия. При равностойни цветови палитри PNG издухва GIF. Photoshop например подхранва идеята, като не се справя добре с енкдоирането в PNG. Ето и картинки за сравнение, за компресия съм използвал ACDSee 3.1, която си ми е и стандартната програма за гледане на картинки (а не вградената в Windows):

http://pics.softvisia.com/design/pics/1654/01-calc-jpg1.JPG

1) - JPG (на максимално качество) - изглежда добре, но като размер е 41,2KB;

 

http://pics.softvisia.com/design/pics/1654/02-calc-jpg2.JPG

2) - JPG (на стандартно за ACDSee 3.1 качество) - размерът пада на 15,1KB, но се вижда силно влошаване на качеството на границите на смяна на цветовете. Особено забележимо е около буквите, които са размазани.

 

http://pics.softvisia.com/design/pics/1654/03-calc-gif.GIF

3) - GIF - определено по-добре от JPG и то за 16,3KB. Ще жертваме 1KB в името на чисто изображение в случая. Е, ако се увеличи, се забелязват някои неправилни цветове, но това са бели кахъри и като цяло не пречат.

 

http://pics.softvisia.com/design/pics/1654/04-calc-png.PNG

4) - PNG - идеално - няма замазване, няма неточни цветове при увеличение, всичко е както трябва да е. На всичкото отгоре при размер 9,08KB. В случая ACDSee не намаля палитрата и въпреки това компресията е по-добра.

 

http://pics.softvisia.com/design/pics/1654/05-calc-png-FS.png

5) - PNG (компресирано с FastStone Image Viewer и намалена цветова палитра на 256 цвята) - забелязва се лек дефект при цвета на бутона вдясно, както и на иконката на калкулатора в най-горната лява част, но се преживява. Резултатът: 5,39KB.

 

Спокойно можете да си запазите картинките и да си ги увеличите, за да се убедите в думите ми.

[Tragedy]

Искам само да допълня, че за картинките аз използвам програмата FastStone Capture, с която правя "снимка" на приложението и я запаметявам в PNG формат.

 

Ето и настройките на програмата:

http://pics.softvisia.com/design/pics/FastStoneSettings.PNG

 

Аз лично избрах PNG, защото прави изображенията с достатъчно малки размери, като запазва цветовете и преливанията на цветове, за разлика от GIF.

[vesodimov]

В подкрепа на Night_Raven : дори смятам, че "Ръководства в процес на разработка" следва да бъде задължителен за използване. Защото там е мястото, ако трябва да се даде съвет по темата. А ако ревюто или ръководствата се пусне директно като готова тема и има неща за дооправяне ... става неприятно както за автора, така и за останалите потребители. И темата се изпълва с мнения и коментари.

 

Предложение към екипа на форума: ревюта или ръководства, които не са минали като "чернова", пуснати са директно като нова тема, а по тях има още работа, да бъдат премествани в "Ръководства в процес на разработка" и авторът да бъде уведомен за това заедно с предложенията или съветите по темата.

 

Идеята е когато потребител влезе във форума да получи достъп до "финална версия" на дадена статия.

[Night_Raven]

Съгласен съм, че е добре ако даден материал има нужда от още обработка да се премества в съответния раздел, но разделът не би било редно да е задължителен. Не мисля, че е редно да задължаваме потребителите подобни неща. Много препоръчителен - да, но задължителен - не.

[Tragedy]

Въпроса определено е интересен, защото от една страна и на мен ми се иска да въведем един добър стандарт за качество на ревютата и статиите и те да минават евентуално през раздела за чернови. Така останалите потребителите и екипа ще могат да дават своите съвети и в последствие да се публикуват в разделите за ръководства. Така темите в разделите за ръководства ще са изчистени и в тях ще могат да се публикуват въпроси и допълнения, а в раздела за черновите да се дообработват ръководствата.

 

Но съм съгласен и с Night_Raven, че може би не е удачно да задължаваме потребителите да пускат статиите си първо при черновите, особено ако смятат, че са завършени и нямат нужда от допълнителни съвети.