Formátování dokumentace

Honza M. napsal(a):

…

Jsi-li graficky zběhlý, co kdybys zkusil vytvořit nějaký návrh a ostatní by o tom podiskutovali? Ono většinou tyhle akce chtějí nějakého „tahouna“, který něco vymyslí a rovnou se pustí do realizace (viz. Tomík se svým screencastem, Inza s NDP a další, kterým se omlouvám, že si na jejich jména teď nevzpomenu) – a ostatní pak rádi přihodí nápady či připomínky. Ale chce to někoho, kdo to rozjede… ;)

Jinak nápad to je dobrej. Určitě by to taky chtělo dál pracovat na obsahu, ten je nosný. Taky by se hodilo navrhnout lepší strukturu webu, mám totiž pocit, že se z dokumentace začíná stávat rozcestník pro všechno možné (viz. položky O Frameworku, Repozitář pluginů,…). Ono vůbec bych řekl, že obsahově web začíná přerůstat přes původně navržený design – ač je velmi pěkný, byl navržen pro menší web a nyní mu přestává dostačovat – především ve struktuře navigace. A také, protože je koncipovaný jako Wiki, jsou následně některé stránky „znásilňovány“ (třeba Repozitář pluginů by si zasloužil zcela jiný layout – viz. níže)

Bohužel, jsem na tom stejně, jako Adent, takže toho moc udělat nemůžu. Při tom mám třeba v hlavě představu o stránce s pluginy, kterou bych viděl trochu jinak: třeba v seznamu pluginů vždy u každého pluginu obrázkový náhled a napravo pak název, autor a popis. Jen mít nějakého grafika, který tu představu uchopí a dokáže graficky dobře ztvárnit.

No, rozepsal jsem se, až to není hezký – tak přenechávám prostor dalším=)

Údajně se o to postará Inza psal na IM. Kdyby ne, tak něco zkusim.

No mě se to líbí, ale když jsem se na tu stránku podíval, tak mi nebylo jasné, který nadpis má jakou prio. :( To by chtělo nějak barevně vymyslet. Třeba podle sytosti barvy + velikost písma?

Mně se to v podstatě líbí, jen tim formátováním nadpisů mi to celé jakoby splývá…opticky se mi nedaří rozpoznat rozdíl mezi nadpisy. U toho h3 bych možná zkusil jen jakoby podtržení po celé šířce? Barvu kbych klidně nechal. To by mohlo být méně výrazné, tak by pak h2 opravdu byl vidět :-) Ale jinak to působí moc pěkně :-)

Vyrobil jsem druhou verzi. První verze je stále k dispozici, tak můžete srovnávat.

Změny:

• h3 je méně výrazný, zkusil jsem to podtržení
• přidal jsem nahoru obsah
• popisky typu „PŘÍKLAD“ jsem dal šedě, aby byla dokumentace méně barevná
• světlejší pozadí příkladů

H2 podle mě musí být agresivní. V současnosti není a dokumentace je pak nepřehledná.

P.S.: Když se teď na to koukám, tak mi to přijde možná lepší bez zaoblených rohů.

Editoval Honza M. (26. 6. 2009 11:30)

Honza M. napsal(a):

Vyrobil jsem druhou verzi. První verze je stále k dispozici, tak můžete srovnávat.

Změny:

• h3 je méně výrazný, zkusil jsem to podtržení
• přidal jsem nahoru obsah
• popisky typu „PŘÍKLAD“ jsem dal šedě, aby byla dokumentace méně barevná
• světlejší pozadí příkladů

H2 podle mě musí být agresivní. V současnosti není a dokumentace je pak nepřehledná.

P.S.: Když se teď na to koukám, tak mi to přijde možná lepší bez zaoblených rohů.

Pěkné, druhá verze se mi líbí víc. Zaoblené rohy bych dal také klidně pryč.
Obsah kapitoly je super věc, ale myslím, že je tam zbytečně použit malý font.
Barva pozadí příkladů tmavší byla asi lepší v první verzi, člověk kolikrát hledá jen příklady
a takhle pro mě trochu splývají s ostatním textem.

Podle mého vypadá ten druhý návrh také dobře. Připojuji se k názoru, že by si obsah zasloužil větší font. A možná číslování úrovní? Za vzor beru dokumentaci Zend frameworku, kde mi to celkem sedí. Jen si teď nevybavuju, zda to jde zařídit pomocí CSS, nebo by se to muselo upravit programově – ručně by to byl strašný opruz.

S číslováním, to je dobrý nápad. Ještě mě napadlo, u toho horního „obsahu“ bych místo ul zkusil ol a možná jednotlivým li nastavil margin, třeba to lépe opticky rozdělí.

A ještě…taková zvrácenost, ale možná to bude hezké…uplně první sekci, se základními informacemi a příkladem, scuknout na nejakých 75% šířky a ten klikací obsah dát na pravou stranu do těch zbylých 25%? On ten obsah zbytečně zabírá spoustu místa a jeho pravá část je dosti nevyužitá. Ale možná to bude vypadat zběsile :-D

EDIT: a nebo ještě jinak, udělat ten obsah rozklikávací…byl by jen link v pravém horním rohu a po kliku by se vysunul…po nějakým timeoutu by se po mouseout zas zasunul…ušetřilo by se místo a možná by to bylo i pěkné. Aby byl ten link viditelný, mohla by se před něj umístit jakási ikonka :-)

Editoval Warden (26. 6. 2009 12:30)

jasir napsal(a):
Zkusil jsem to, při 30% šířce boxiku s obsahem, float:right a normální velikosti písma to vypadá dost dobře. Jsem pro.

Taky jsem teď zkoušel a vypadá to hezky ikdyž se to nevysouvá. Mno uvidíme co další a co Honza :-)

A co ten h3 nadpis nechat s pozadím, jako byl předtím, ale světlejší, třeba #E6D8B2?

No ten obsah určitě napravo…

Základní informace bych více zvýraznil – to je to čeho si musíš všimnout jako prvního…

Dále je ta stránka už i někde na nette wiki nebo zatím jen na tom tvém webu?

Honza M. napsal(a):

přidal jsem nahoru obsah

výborné :)

popisky typu „PŘÍKLAD“ jsem dal šedě, aby byla dokumentace méně barevná

Viem, že tie popisky boli už aj v pôvodnom texte, no sú vôbec nutné? Podľa mňa ak sa v dokumentácii bude nachádzať blok kódu, tak pôjde v drvivej väčšine o príklad…

světlejší pozadí příkladů

Podľa mňa ideálne

H2 podle mě musí být agresivní. V současnosti není a dokumentace je pak nepřehledná.

Beriem, samému sa mi pomaly začína páčiť :)

H2/H3 problém som mal v hlave inak, preto som si aj ja dovolil ukážku. Hlavne preto, že:

• myslím si, že nadpisy na rôznej úrovni by mali mať aspoň niečo spoločné, aby sa text ľahko vizuálne delil na časti; ak boli oba s pozadím nebolo jasné, ktorý je dôležitejší, v Honzovej druhej verzii mi zase H3 splýva s textom – ja som skúsil H2-pozadie & H3-podčiarknutie, ale rovnakej farby → dôležitosť je jasná a pripadá mi to krajšie. Oba nadpisy majú u mňa rovnakú veľkosť písma (čo mi až tak nevonia), ale keď je H3 menší, stráca sa.
• Nie som si istý popiskami Obsah+Základné informácie, pripadá mi jasné, že ide o obsah/základné informácie, no bez nich mi to tiež dáko neladí.
• Popisky „Příklad:“ som vyhodil, namiesto toho by byť zaujímavé priradiť k (niektorým) príkladom krátky popisok (len môj experiment).
• zvýraznenie kódu farbami, ktoré sa používajú na nadpisy sa mi stále nepáči – prispieva to k jednoliatosti textu, čo myslím nie je dobre – použil som farby z terajšej dokumentácie s tým, že majú trochu nižšiu sýtosť (experiment). Ideálny stav podľa mňa je, ak sa farba nadpisu použije len na nadpis. Aj preto som farbu okraju kódu zmenil zo sivomodrej na sivú – mňa rušil.

spravil som aj viacero kozmetických zmien preto, že tak sa to páči viac mne a nemusí to znamenať to, že sa to páči i ostatným. Snáď to dopomôže k lepšej dokumentácii pre všetkých…

Ty příklady ve třetí verzi vypadají moc dobře. Jak už tu někdo psal, možná nechat u zvýrazňování syntaxe původní veselé barvičky. Jinak je to ale fajn, i ta popiska Příklad se mi líbí, je to dobře rozeznatelné od zbytku stránky.

Obsahové menu by zasloužilo nějaké odsazení (i svislé) a možná nějaký druh odrážek…?

Snad jen nápis Základní informace na mě působí ošklivě. Možná ho dát pryč a základním informacím dát větší písmo.

Ještě na mě ta stránka působí tak trochu smutně, ale to je asi těma barvama a ty jsou už zajetou Nette identitou.

Kravco, ten nápad s popiskem příkladu mi případá velmi dobrý. Stejně tak změny nadpisů jsou u Kravca dle mého přehlednější, h3 tolik nepoutá pozornost a je skutečně podnadpisem.

To posunutí obsahu vpravo nahoru je pěkné v případě kratších obsahů. Otázka je, jak to bude vypadat. A další, jestli někdy budeme mít tak dlouhé obsahy :-)

Rozhodně úctyhodná práce od všech!

BigCharlie: v případě delších obsahů začnu velmi rychle uvažovat o navrácení menších písmenek a menších řádků ;-)

Zkusil bys u těch příkladů dát pryč to zakulacení rohů a zmenšit border na 1px (on teď má pre nastavený 1, ale nějak se to tam kumuluje asi a vypadá to na 2 :-)? Ten nadpis „Příklad“ bych tam nechal, mohlo by to vypadat docela dobře.

A šel by ten nadpis „Obsah kapitoly:“ zarovnat s horním okrajem toho hlavního textu „Nette\Web\Html je malý pomocník pro generování (X)HTML kódu…“? Teď je pár pixelů pod a nevypadá to moc pěkně :-)

Honza M. napsal(a):

Přeci nebudeme ladit syntaxi do „korporátních barev“, to mi přijde na šišku :)

Koukal jsem na jiné dokumentace. jQuery – bez zvýraznění, Zend – bez zvýraznění, prototype.js – téměř korporátní barvy

Podle mě současné barvy strašně moc křičí. Přitom mi nepřijdou ani nijak klasické, protože jsem je nikde jinde neviděl. Možná jsou v phpEdu, nejsem si jistý. (Téměř) korporátní barvy jsem zvolil proto, aby kód ladil se zbytkem stránky.

Jo, tak teď už jsme u vkusu. Fakt je, že používám PhpEd – černé pozadí, celkem výrazné barvy…
Mě zase přijdou barvy v návrhu takříkajíc „vyblité“ :) No tak neva, no. :-D

je to velice elegantní

Nepopírám.

krásně to vystihuje fakt, že jde o perex

To já právě nechci. Na úvod podle mě patří krátký odstavec, kde získám stručnou, ale kompletní informaci. Pod pojmem perex si představím jednu nic neříkající větu, kterou někdo musel vymyslet, protože to vypadá hezky :)

Popisek základní informace dát pryč.

Už je pryč.

To já právě nechci. Na úvod podle mě patří krátký odstavec, kde získám stručnou, ale kompletní informaci. Pod pojmem perex si představím jednu nic neříkající větu, kterou někdo musel vymyslet, protože to vypadá hezky :)

ok :) perex – co to vůbec je? – jsem napsal, jak tak koukám do toho csska… <p class=„perex“></p>

Na úvod podle mě patří krátký odstavec, kde získám stručnou, ale kompletní informaci.

na tom se shodnem :)

proč nechceš aby tento důležitý odstavec měl náležitý šmrnc?

Tohle je další typickej příklad komunikace kterou by bylo lepší řešit na komunitním IRC/jabberu (nebo zítra na sobotě) a na fórum dávat jen průběžné výsledky diskuze. ;]

jasir napsal(a):

Mě zase přijdou barvy v návrhu takříkajíc „vyblité“ :) No tak neva, no. :-D

Súhlasím s Honzom, že farby by mali byť vyblité, no ako som už písal, problém vidím v tom, že pri súčasnej farebnosti je to celé premodralé, podľa mňa by vo zvýrazňovaní syntaxe modrá nemala byť zastúpená.

Honza M. napsal(a):

Ve čtvrté verzi jsem zapracoval některé kravčovy nápady.

Nie, nekomolíš :)

líbí se mě to pořád víc a víc… a teď neco konstruktivnějšího… popis/perex říkejte si to mu jak chcete bych dal kurzívou. A „obsah kapitoly“ bych udlělal stejným stylem jako příklady (zkoušel jsem to ve Firebug-u a vypadá to pěkně. Co se týká barev sintaxe tak ať už budou jaké budou tak mě se líbí ty co jsou na API a dokonce jsem si je dal do IDE.

A co tohle?:

…„obsah kapitoly“ bych udlělal stejným stylem jako příklady (zkoušel jsem to ve Firebug-u a vypadá to pěkně…

Jen dodám že se to týká toho nadpisu „obsah kapitoly“…

Zkusil jsem trošku upravit web a přidat tam ty generované obsahy