Svenska ElektronikForumet

Hej
Jag gissar att det lästs ett par fackböcker av alla medlemmar här, kanske har det även skrivits en och annan.

Jag och min ena grabb har studerar programmering tillsammans under en period och jag dokumenterar nu allt vi lärt oss.
Det blev så att jag skriver det som att någon ska läsa och det är ju bra så jag o grabben kan läsa igenom när vi glömt, hehe.

Så! Ska man likna en bok så är det väl lika bra att man få till det så bra som det bara går. Tänkte därför efterlysa lite tips.
Hittills har "boken" kapitel med en liten inledning om vad kapitlet i fråga innehåller. I kapitlen finns rubriker.
Varje kapitel innehåller förklaringar, exempel kod (formaterad), bilder och en avslutande och förhoppningsvis inspirerande "uppgift" för att själv testa funktionen.

Funderar på om man kanske ska ha med vissa delar som markerade "faktarutor" och hur faktarutor upplevs? Vad anser vi om faktarutor?
Tanken är att det kan dela upp och strukturera en aning.

Hur vill man själv ha en fackbok när man ska lära sig ett ämne? Finns det några bra grundregler för att optimera upplevelsen kanske?

Kul ide'! Det är nog olika hur man vill ha det. Faktarutor kan lätta upp tycker jag. Det finns mycket på nätet, och många böcker om böcker, men varför inte utgå från formatet på en bok ni gillar?

När jag pluggade 80 poäng elektronik på KTH gick vi en kurs som i princip gick ut på att vi skulle lära oss skriva manualer.

Jag har för mig att vi där pratade just om att man måste tänka på att det finns flera olika anledningar till att folk läser en manual, så det måste alltså vara anpassat efter flera olika typer av läsare. Nu är väl detta inte helt tillämpbart i ert fall, men det kan ge några tankeställare.

Dels behövs nån form av index för referens-användning, när du undrar "hur f-n var det man gjorde det där nu igen?". Tittar man t.ex. i manualen för en bil finns det ett index, men det finns också bilder med förklaring av varenda knapp, spak och indikeringslampa, med referenser till de sidor där funktionen beskrivs.

Sen behöver varje kapitel inledas med en kort introduktion om varför man ska läsa det, så man inte sitter och läser ett helt kapitel för att sen inse att "det jag undrade över stod inte där".

I en manual behövs också en felsökningsguide, när saker inte fungerar, vad ska man prova först?

En manual kan också behöva förklara vissa begrepp eller en terminologi, och lika vanligt är det nog att definiera en terminologi ("när vi säger så här så menar vi det här").

Man behöver också tänka på att förklara självklarheter. I en manual till cykel räcker det inte med att skriva "pumpa däcket till 1 bar", man måste förklara att det behöver göras med en cykelpump med en anslutning som passar ventilen. Annars står folk där och försöker pumpa med en luftmadrasspump eller nåt.

I hjälpfunktionen för en app kanske man måste förklara begrepp som "långtryck" eller "pinch zoom", för de är inte självklara för alla.

Ur ett annat perspektiv: för att få en bok som är lättläst ur ett typografiskt synsätt, läs boken Typografisk Handbok av Christer Hellmark.

Ja, egentligen är frågan lite tvetydig.

Rubriker frågar om layout, men själva inlägget verkar fråga om struktur på innehållet. Jag försökte svara på det senare.

Ofta behöver man anpassa layouten efter vad man ska ha för innehåll utöver löptexten. Ska det vara en massa diagram behöver man t.ex. anpassa för det, ska det vara en massa formler eller tabeller behöver man anpassa för det. I det här fallet antar jag att det kommer att vara en hel del programkod.

Löptexten ska ju helst inte vara mer än 60-70 tecken per rad, det kan innebära att om sidorna ska anpassas för diagram så kan man behöva ha löptexten i tvåspalt, eller vid andra tillfällen behöva ha en smal spalt med stora marginaler att lägga diagram och bilder i.

Vad som är bäst.....då hade nog de flesta författare valt den layouten. Jag gillar layouten i Newnes RF Circuits av Bowick. Och även formatet.

Tack.. bra tips

Ett av de vanligare sätten att strukturera innehåll i fackliteratur där det inte går ut på att
i första hand utnyttja "konstnärlig frihet" utan överföra kunskap är att låta kraven på
förkunskaper styra. Både på högsta nivån, vem är boken avsedd för och i vilken ordning
fakta sedan presenteras.

Den högsta nivån avgör vad som behöver förklaras i detalj och vad som är självklarheter
för dom som kommit dit t.ex. genom godkänt i tidigare kurser. En sammanfattning i inledningen
kan göra det lättare att komplettera luckorna, "Du som läser denna bok förutsätts kunna...
... och om inte så rekommenderas xxxxx.

Innehållet ända ner i minsta detalj måste följa något system där delarna beskrivs före denna
kunskap senare används. Man kan också börja högt upp i hierarkin och gräva sig neråt i
detaljerna. Att rita upp en trädstruktur där man ser vad som bygger på vad underlättar.
Att hatta fram och tillbaka i nivåerna och mellan grenarna är ingen höjdare, ställer onödigt stora
krav på läsaren. En hel vägg på många kvadratmeter gick åt när jag förr skrev om ny och (då)
komplicerad teknik. Uppdelningen från "hela klabbet" ner till "minsta detalj" kan resultera i olika
antal huvudgrenar men det är vad som naturligt hänger ihop (i det man vill beskriva) som styr.

Fackuttryck och förkortningar (ex. TLA (sv. TBF)) förklaras om det inte är en självklar förkunskap.
"Lagom" meningslängd och ordlängd underlättar:
https://sv.wikipedia.org/wiki/L%C3%A4sbarhetsindex